Zapier Formatic Integration
Endpoint- AUTHENTICATION
POST {base_url}/api/login
Description
This endpoint allows users to log in by verifying their credentials (email and password). If the credentials are correct, it generates an access token for the user and updates the login details (last login, last active, user agent). If this is the user's first login, it also records the timestamp of their first login.
Request
Headers
Accept: application/json
Content-Type: application/json
Request Body
The request body must be a JSON object containing the following fields:
FieldTypeRequiredDescription email emailYes Email used by user to login into formatic.password password YesPassword of the user.
Example Request Body
json
{
"email": "user@example.com",
"password": "yourpassword"
}
Response
Success Response
Status Code: 201 Created
Response Body:
json
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YjY1NDUzNS1hNjI4LTRhMzMtODdmYy1iMDhlMDQzZTgzYTkiLCJqdGkiOiI0YmZiZTRlNzNkOTdkOTZkOTI2MzAzYzc3YjM2MGVmNTY0YjcyNzU3Nzg3NTNkZjJmZGUwZjRiNzkwY2UyMjUyOWFmZTA2YTgwZDQ4YzlhMCIsImlhdCI6MTcyODk2NTcxOS45Njg4MDUsIm5iZiI6MTcyODk2NTcxOS45Njg4MDksImV4cCI6MTcyOTA1MjExOS42NDE3MDgsInN1YiI6IjEwMDIiLCJzY29wZXMiOltdfQ.OQAV9M39d7HgyXRk6mEktXhkX-jCrlIJ2i8bhs5rvW7YAQfcaEgiU5TmnMRmLfGsa6QMyQVkSH-d4AyadmyIxSez_7qw0Vb91wwaiGjWwMQ6jsFm_d_eLPZvr2btn-l2VybWDFRUnDBH5KKfSGeXfbfflD-spSle5f3wcMPb6mQLcT_Uw8EQg37KKsX21r0c5CwD8qgumxULX1bHO7KW9JmUepb2LSvQ-xjywBi5ex_PSq3BxmJWmRLTke6qP0Mm8vHqGNb25Ne_DE9kJsBztdqwH4Ooc8Bplkpmyn03oFaonQz7OZKVB1FD9ct3Pn5lrvOnWHcOvtsXGhLE406wn7mEqreBVqm5_BPgjv3HrfVB-RyIk74Ltaa7DjFKeqN7Vqqg4SxEbCocPiSXLFxHuIkbVtbtqNl3OpN--66Jz1Y61NVKYXmcoDx1iM6Yzhsix1i7pXOSMUDkeKCawlh9prpLqDD5DHuvE7mY-AyzzWMejHc8pnKLJijh9nak6Laa6bZTKwvsU9IczyDX-19wgS6kZ6xcxS_zGdiBekkv6V17mvEvBBF16n8TEiOFWskwX674Tvb0rhlFrw3ftCpeU_R-u3DFwEEPN2FueVtpXIPwgFL9IAdNV2MYbW1LLjAyIzBeu2yn7JUfdgK23cMQjhEDs2Ye1Xt5no_xfA_zqUI"
}
Error Responses
· Invalid Password
Status Code: 422 Unprocessable Entity
Response Body (JSON):
json
{
"status": "error",
"message": "Invalid Password",
"data": []
}
· User Not Found
Status Code: 404 Not Found
Response Body (JSON):
json
{
"status": "error",
"message": "User does not exist",
"data": []
}
· Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred",
"data": {
"trace": [ ... ] // Trace details shown in non-production environments
}
}
Additional Notes
This endpoint logs all requests for tracking purposes.
Endpoint-CREATE CARD
POST {base_url}/api//zapier/add-card
Description
This endpoint allows Zapier to create a new card in the Laravel application. It validates the request data and performs various operations, such as checking form access, handling card limits, creating a new card, and associating any media or todos with it.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json
Request Body
The request body must be a JSON object containing the following fields:
FieldTypeRequiredDescriptionlistIdinteger YesThe ID of the list where the card will be created.formIdinteger YesThe ID of the form associated with the card.dataarray NoAn array of data fields for the card. Each entry can be an associative array of field data.mediastring NoA URL to media associated with the card.labelIdinteger NoAn ID for the label to associate with the card.dueDatestring NoThe due date for the card in a valid date format (YYYY-MM-DD).parentIdinteger NoThe ID of the parent card if applicable.rowIdinteger NoThe ID of the row associated with the card.sheetIdinteger NoThe ID of the sheet associated with the card.
Example Request Body
json
{
"listId": 1,
"formId": 2,
"data": {
"questionId1": ["value1"],
"questionId2": ["value2"]
},
"media": "http://example.com/image.jpg",
"labelId": 5,
"dueDate": "2024-12-31",
"parentId": null,
"rowId": 3,
"sheetId": 4
}
Response
Success Response
Status Code: 201 Created
Response Body:
json
{
"message": "From Zapier Card created successfully.",
"data": {
"newCard": {
// Card details including media and todos
},
"errors": {}
}
}
Error Responses
Validation Error
Status Code: 422 Unprocessable Entity
Response Body:
json
{
"message": "Validation Error",
"errors": ["Field validation messages"]
}
Form Not Found
Status Code: 404 Not Found
Response Body:
json
{
"message": "Form not found.",
"errors": []
}
Card Limit Reached
Status Code: 400 Bad Request
Response Body:
json
{
"message": "The card limit has been reached.",
"errors": []
}
Invalid URL
Status Code: 422 Unprocessable Entity
Response Body:
json
{
"message": "The url is not valid.",
"errors": []
}
Additional Notes
This endpoint logs all requests for tracking purposes.
The data field allows for flexible input as it supports an array of question IDs and their corresponding values.
Ensure that the dueDate is a future date; otherwise, a validation error will be returned.
Endpoint-UPDATE CARD
PATCH {base_url}/api/zapier/update-card
Description
The updateCard endpoint allows users to update the details of an existing card in a form, including card metadata, form data, due dates, media files, and labels. The endpoint validates user access to the form, updates the card's data, processes any media attachments, and sends real-time updates via Pusher.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json
Request Body
The request body must be a JSON object containing the following fields:
FieldTypeRequiredDescriptionlistIdintegerYesThe ID of the list where the card will be updated.formIdintegerYesThe ID of the form associated with the card.rowIdintegerYesThe ID of the card (row) to be updated.titlestringNoThe new title of the card.descriptionstringNoThe new description of the card.dataarrayNoArray of form data. Keys are question IDs, and values are arrays of answers.mediastringNoThe URL of the media file to attach to the card.dueDatestringNoThe due date to be assigned to the card (format: Y-m-d).labelIdintegerNoThe ID of the label to apply to the card.parentIdintegerNoThe parent card ID (if applicable).uuidstringNoA unique identifier for the card.
Example Request Body:
json
{
"listId": 12,
"formId": 3,
"rowId": 45,
"title": "Updated Card Title",
"description": "This is an updated description for the card.",
"data": {
"1": ["Option 1", "Option 2"],
"2": ["Yes"]
},
"media": "https://example.com/image.jpg",
"dueDate": "2024-10-20",
"labelId": 4,
"parentId": 20,
"uuid": "123e4567-e89b-12d3-a456-426614174000"
}
Response
Success Response
Status Code: 201 Created
Response Body:
json
{
"message": "From Zapier edited the card.",
"data": {
"id": 45,
"title": "Updated Card Title",
"description": "This is an updated description for the card.",
"dueDate": "2024-10-20",
"media": "https://example.com/image.jpg",
"labelId": 4,
"parentId": 20
},
"errors": []
}
Error Responses:
Validation Error (422):
json
{
"message": "Validation Error",
"errors": [
"The dueDate is not a valid date."
]
}
Form Not Found (404):
json
{
"message": "Form not found."
}
Record Not Found (404):
json
{
"message": "Record not found."
}
Invalid Media URL (422):
json
{
"message": "The URL is not valid."
}
Additional Notes
The updateCard method validates input using Laravel's Validator. The media field must be a valid URL, and the dueDate must be a valid date formatted as Y-m-d.
The method checks if the user has access to the form and whether the user is a member of the form. If any condition fails, appropriate error messages are returned.
If media files are attached, they are sanitized and stored. The method logs card updates and media attachments.
Pusher notifications are sent to notify users of the card updates in real-time.
Endpoint – GET BOARDS
GET {base_url}/api/database?limit=100&page=1&type=&search=&slim=1
Description
This endpoint returns a list of boards. The data is returned in a structured format under the databases key.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json.
Response
Success Response
Status Code: 200
Response Body:
json
{
"message": "Success",
"data": {
"databases": [
{
"id": 4185,
"title": "DailyTasks",
"description": null,
"boardTitle": "DailyTasks",
"type": "customForm",
"userId": 1007,
"meta": {
"shareableId": "form-670371aa82879",
"iconType": "custom-board",
"logo": {
"size": 0,
"alignment": "justify",
"dimension": ""
}
}
},
{
"id": 4180,
"title": "Test",
"description": null,
"boardTitle": "Test",
"type": "customForm",
"userId": 1002,
"meta": {
"shareableId": "form-66f26a62d8230",
"iconType": "custom-board",
"logo": {
"size": 0,
"alignment": "justify",
"dimension": ""
}
}
},
{
"id": 4181,
"title": "test2",
"description": null,
"boardTitle": "test2",
"type": "customForm",
"userId": 1002,
"meta": {
"shareableId": "form-66f3ec42d5969",
"iconType": "custom-board",
"logo": {
"size": 0,
"alignment": "justify",
"dimension": ""
}
}
}
],
"total_count": 3
}
}
Error Responses
1. Authorization Error
Status Code: 401 Unauthorized
Response Body (JSON):
json
{
"status": "error",
"message": "Unauthorized access.",
"data": []
}
2. Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred.",
"data": {
"trace": [ ... ] // Omitted in production environments
}
}
Additional Notes
Not Applicable.
Endpoint – GET LISTS ASSOCIATED WITH BOARD
GET {base_url}/api/flowboard/forms/formId?sortBy=asc&label=&search=&assignee
Description
This endpoint returns lists associate with boards. The data is returned in a structured format under the form_lists key. This api also return other data but we are specific only to form_list key which return lists associated with board.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json
Example Request Body
GET /{base_url}/api/flowboard/forms/4188?sortBy=asc&label=&search=&assignee
Authorization: Bearer Token
Response
Success Response
Status Code: 200
Response Body:
json
{
"status": "success",
"message": "success",
"data": {
"form_lists": [
{
"id": 14753,
"formId": 4185,
"title": "High Priority Tasks"
},
{
"id": 14754,
"formId": 4185,
"title": "Low Priority T"
},
]
}
}
Error Responses
Authorization Error
Status Code: 401 Unauthorized
Response Body (JSON):
json
{
"status": "error",
"message": "Unauthorized access.",
"data": []
}
Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred.",
"data": {
"trace": [ ... ] // Omitted in production environments
}
}
Additional Notes
This API return overall data but we are concerned with form_list key and its data.
Endpoint – GET FIELDS
GET {base_url}/api/zapier/form-fields/{formId}
Description
This endpoint is used to retrieve the form fields associated with a specific form based on the formId. The fields are transformed to have sanitized keys and their respective titles as labels, ensuring compatibility with Zapier.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json
Request Body
The request body must be a JSON object containing the following fields:
Path Parameters
FieldTypeRequiredDescriptionformIdintegerYesThe ID of the form to retrieve fields for.
Example Request Body
GET /form-fields/12345
Authorization: Bearer Token.
Response
Success Response
Status Code: 200
Response Body:
json
{
"message": "success",
"data": {
"fields": [
{
"key": "fieldsZapier_f67050b5fd8282",
"label": "Titleeee"
},
{
"key": "fieldsZapier_f67050b5fe2436",
"label": "Description"
},
{
"key": "fieldsZapier_f67050b5fe2f42",
"label": "Priority"
}
]
}
}
Error Responses
Form Not Found
Status Code: 404 Not Found
Response Body (JSON):
json
{
"status": "error",
"message": "Form not found.",
"data": []
}
Authorization Error
Status Code: 401 Unauthorized
Response Body (JSON):
json
{
"status": "error",
"message": "Unauthorized access.",
"data": []
}
Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred.",
"data": {
"trace": [ ... ] // Omitted in production environments
}
}
Additional Notes
The form access is validated using the checkFormAccess() method, ensuring that only authorized users can access the form.
Fields' keys are sanitized for compatibility by removing special characters and ensuring the key starts with a letter.
Error details include stack traces in non-production environments.
Endpoint – GET LABELS
GET {base_url}/api/labels
Description
This endpoint returns a list of labels associated with board and cards. The data is returned in a structured format under the labels key.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json.
Response
Success Response
Status Code: 200
Response Body:
json
{
"message": "Label data!!",
"data": {
"labels": [
{
"id": 90864,
"title": "On Hold",
"value": "#9b9b9b",
"created_at": "2024-07-31T07:28:08.000000Z",
"updated_at": "2024-07-31T07:28:08.000000Z",
"userId": 1002,
"isDefault": 0
},
{
"id": 90863,
"title": "High Priority",
"value": "#d0021b",
"created_at": "2024-07-31T07:28:08.000000Z",
"updated_at": "2024-07-31T07:28:08.000000Z",
"userId": 1002,
"isDefault": 0
}
],
"total_count": 2
}
}
Error Responses
3. Authorization Error
Status Code: 401 Unauthorized
Response Body (JSON):
json
{
"status": "error",
"message": "Unauthorized access.",
"data": []
}
4. Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred.",
"data": {
"trace": [ ... ] // Omitted in production environments
}
}
Additional Notes
.Not applicable
Endpoint – GET dummy lists
GET {base_url}/api/zapier/dummy-lists
Description
This endpoint returns a list of dummy lists, each associated with a form. The data is returned in a structured format under the form_lists key.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json
Example Request Body
GET /dummy-lists
Authorization: Bearer Token
Response
Success Response
Status Code: 200
Response Body:
json
{
"status": "success",
"message": "success",
"data": {
"form_lists": [
{
"id": 14753,
"formId": 4185,
"title": "Morning"
},
{
"id": 14754,
"formId": 4185,
"title": "Lunch"
},
{
"id": 14755,
"formId": 4185,
"title": "Evening"
},
{
"id": 14756,
"formId": 4185,
"title": "Dinner"
},
{
"id": 14763,
"formId": 4185,
"title": "Task"
}
]
}
}
Error Responses
Authorization Error
Status Code: 401 Unauthorized
Response Body (JSON):
json
{
"status": "error",
"message": "Unauthorized access.",
"data": []
}
Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred.",
"data": {
"trace": [ ... ] // Omitted in production environments
}
}
Additional Notes
The dummy associated list is hardcoded to run zap as id is dynamically fetched so when we run single zap id become null and error is return to incorporate that it is made and it provide solid base for documentation.
Endpoint – get dummy cards
GET {base_url}/api/zapier/dummy-cards
Description
This endpoint returns a list of dummy cards, each with an ID and name. The data is returned in a structured format under the dummy_cards key.
Request
Headers
Authorization: Bearer token (for authenticated access)
Content-Type: application/json
Example Request Body
GET /dummy-cards
Authorization: Bearer Token.
Response
Success Response
Status Code: 200
Response Body:
json
{
"status": "success",
"message": "success",
"data": {
"dummy_cards": [
{
"id": 168430,
"name": "168430 | f67050b5fd8282 | "
},
{
"id": 168438,
"name": "168438 | f67050b5fd8282 | To Test successfull triggers"
},
{
"id": 168439,
"name": "168439 | f67050b5fd8282 | GoogleSheetToFormatic5"
},
{
"id": 168440,
"name": "168440 | f67050b5fd8282 | New Card"
},
{
"id": 168441,
"name": "168441 | f67050b5fd8282 | This is title"
},
{
"id": 168442,
"name": "168442 | f67050b5fd8282 | This is card"
},
{
"id": 168443,
"name": "168443 | f67050b5fd8282 | card title 2024-10-29"
}
]
}
}
Error Responses
5. Authorization Error
Status Code: 401 Unauthorized
Response Body (JSON):
json
{
"status": "error",
"message": "Unauthorized access.",
"data": []
}
6. Server Error
Status Code: 500 Internal Server Error
Response Body (JSON):
json
{
"status": "error",
"message": "An error occurred.",
"data": {
"trace": [ ... ] // Omitted in production environments
}
}
Additional Notes
The dummy card list is hardcoded to run zap as id is dynamically fetched so when we run single zap id become null and error is return to incorporate that it is made and it provide solid base for documentation.
Table OF Reference base urlhttps://api.dev.myformatic.com/ Form IDIT refers to the board List IdIt refers to the lists Row IdIt refers to the card id