Help and support

Form Design API: Your Gateway to Data Extraction

The Form Design functionality in Artificio is at the heart of its data extraction prowess. It allows you to visually construct forms that define the data you want to collect. More importantly, each form you design can be instantly transformed into a functional API, ready for integration.

1. How to Design a Form

1. Navigate to Form Designer: From your Artificio dashboard, locate and click on the "Form Design" or "Create App Form Design" button.
2. Name Your Form: Provide a meaningful name for your form (e.g., "TimesheetsData"). This name will typically be used in the generated API endpoint.
3. Add Fields: Drag and drop various field types onto your form canvas. Artificio offers a range of field types to suit your data needs:
   • Text Field: For short text inputs (e.g., consultantName, companyName).
   • Text Area: For longer text inputs.
   • Number Field: For numerical data (e.g., hourlyRate, hours, amount).
   • Email Field: For email addresses with built-in validation (e.g., companyEmail).
   • Date Field: For capturing dates.
   • Dropdown/Select: For predefined options.
   • Checkbox: For boolean values.
   • Radio Button: For single selection from multiple options.
   • File Upload: Crucial for attaching files (e.g., file_dataflow-90105-Auto_Receipts).
4. Configure Field Properties: For each field you add:
   • Label: Provide a user-friendly label (e.g., "Consultant Name").
   • Field Name (API Parameter Name): This is critical! Define a unique, descriptive name that will be used as the parameter in your API (e.g., consultantName). Ensure these names are clear and consistent.
   • Validation Rules: Apply validation rules as needed. Common validations include:
     • Required: Ensures the field cannot be left blank (e.g., consultantName, hourlyRate, hours, amount).
     • Min/Max Length: For text fields.
     • Min/Max Value: For number fields.
5. Save Your Form: Once you are satisfied with your form design, click "Save." Artificio will then automatically generate the corresponding API.
6. Click on the API Option from the list to see the details and you can copy the API parameters.

7. You can now access the API Parameters modal for this particular form design to proceed

    

1.2 Example: Designing the TimesheetsData Form

Based on the provided example, here's how you would design the "TimesheetsData" form in Artificio:

2. API Generation and Usage

Once your form is designed and saved, Artificio automatically generates a RESTful API endpoint. This API acts as an interface through which external applications can submit data to your Artificio form.

2.1 API Information (TimesheetsData Example)

• Endpoint: POST https://api-dev.np-artificio.com/external/forms/TimesheetsData
  • Method: POST is used to send data to the server to create or update a resource.
  • URL: The base URL for Artificio's external forms API, followed by your form's name (TimesheetsData).

2.2 API Parameters

These are the fields defined in your Artificio form, which correspond to the data you expect to receive.

2.3 Body Parameters (JSON Example for Non-File Data)

When sending data to the API, you typically structure it as a JSON object for most fields. However, for file uploads, multipart/form-data is required.

JSON

{
  "consultantName": "John Doe",
  "companyName": "ABC Solutions",
  "hourlyRate": "50.00",
  "hours": "40",
  "week": "2025-W28",
  "companyEmail": "info@abcsolutions.com",
  "amount": "2000.00",
  "customerRefValue": "CRV-12345",
  "file_dataflow-90105-Auto_Receipts": "YOUR_FILE_DATA_HERE", // This will be handled differently in multipart/form-data
  "textField": "Project X timesheet",
  "detailType": "Consulting Services"
}

2.4 cURL Command Example for API Interaction

The cURL command is a versatile tool for making HTTP requests and is excellent for testing your API. The provided cURL command demonstrates how to send data to your Artificio form API.

curl -X POST https://api-dev.np-artificio.com/external/forms/TimesheetsData \
  -H 'X-API-Key: YOUR_ARTIFICIO_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'consultantName=John Doe' \
  -F 'companyName=ABC Solutions' \
  -F 'hourlyRate=50.00' \
  -F 'hours=40' \
  -F 'week=2025-W28' \
  -F 'companyEmail=info@abcsolutions.com' \
  -F 'amount=2000.00' \
  -F 'customerRefValue=CRV-12345' \
  -F 'file_dataflow-90105-Auto_Receipts=@/path/to/your/receipt.pdf' \
  -F 'textField=Project X timesheet' \
  -F 'detailType=Consulting Services'

Key Elements of the cURL Command:

• -X POST: Specifies the HTTP method as POST.
• https://api-dev.np-artificio.com/external/forms/TimesheetsData: The target API endpoint.
• -H 'X-API-Key: YOUR_ARTIFICIO_API_KEY': Crucial for authentication. You must replace YOUR_ARTIFICIO_API_KEY with the actual API key generated from your Artificio account. This key authenticates your request.
• -H 'Content-Type: multipart/form-data': Indicates that the request body is sent as multipart/form-data, which is necessary when uploading files.
• -F 'parameterName=value': Used to send form data.
  • For regular text fields, provide the field name and its value (e.g., -F 'consultantName=John Doe').
  • For file uploads, use -F 'file_dataflow-90105-Auto_Receipts=@/path/to/your/receipt.pdf'. The @ symbol tells cURL to read the content of the specified file. Replace /path/to/your/receipt.pdf with the actual path to the file on your system.

2.5 Integrating with Other Applications

The generated API can be integrated into virtually any application that can make HTTP requests. Here's a general approach:

1. Identify Your Application's HTTP Client: Most programming languages (Python, JavaScript, Java, C#, PHP, etc.) have built-in libraries or popular third-party clients for making HTTP requests (e.g., requests in Python, fetch in JavaScript, HttpClient in C#).
2. Construct the Request:
   • URL: Use the API endpoint provided by Artificio.
   • Method: Set the method to POST.
   • Headers: Include the X-API-Key header with your Artificio API key and the Content-Type: multipart/form-data header if you are sending files.
   • Body: Construct the request body using key-value pairs corresponding to your form fields. For file uploads, ensure your HTTP client handles multipart/form-data correctly.
3. Handle the Response: After making the request, the Artificio API will typically return a JSON response indicating success or failure.
   • Success: A 2xx status code (e.g., 200 OK, 201 Created) usually means the data was successfully received and processed by Artificio. The response might include a confirmation message or an ID for the submitted data.
   • Failure: A 4xx or 5xx status code indicates an error (e.g., 400 Bad Request for missing required fields, 401 Unauthorized for invalid API key, 500 Internal Server Error). The response body will often contain an error message detailing the issue.

Where to Find Your API Token:

Your API Token is securely generated within your Artificio account. You can typically find it in one of these locations:

• API Tokens: Look for a section like "Super Admin" within your Artificio dashboard.

Once found, treat your API Token like a password. Do not share it publicly or embed it directly in client-side code where it can be easily exposed.