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

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

• 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

1. Form Not Found

   • Status Code: 404 Not Found

   • Response Body (JSON):

json

{

  "status": "error",

  "message": "Form not found.",

  "data": []

}

2. Authorization Error

   • Status Code: 401 Unauthorized

   • Response Body (JSON):

json

{

  "status": "error",

  "message": "Unauthorized access.",

  "data": []

}

3. 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

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

• 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