Copy page

API Setup

API Response Structure

Brick API responses use a consistent structure so your integration can separate successful data, asynchronous processing messages, metadata, and errors. Use this guide to understand how to parse synchronous and asynchronous responses, map job_id values where provided, and decide when to rely on callbacks or status endpoints for the final transaction result.

Success Response

Sample of Sync Response

Code
{
         "status": 202,
          data:{
               "message": "We are processing your request and will send the data in the callback URL."
               “job_id”:”XXXX-XXXX-XXXX-XXXX”
          },
          metadata:{
               "source": {{API/Widget/Dashboard/SDK/Portal}},
               "entity": {{Data/Insight/Verification/Payment}}
        },
        error: null,
 }

Field description

Field	Description
status	HTTP/HTTPS status code
message	Text message
job_id	Unique transaction_id, It will help to map Async response
source	It defines from where APIs request is coming, It can be either one from API, Widget, Dashabord, SDK or Portal.
entity	It defines which product the APIs request is coming from, It can be either one from Data, Insight, Verification, or Payments.
error	In case of success, error will be null

Sample of Async Response

Code
{
    "status": 200,
     "data": {
            "message": “We are successfully able to fetch data”,
            "example-1":"XXXX-XXXX-XXXX",
            "count":{{Number of objects}},
            "example-2"{[
                 "array1":1,
                 "example-3":"xx-xx-xx"
                 ],[
                 "array2":1,
                 "example-4":"xx-xx-xx"
            ]}
    },
    metadata:{
        "source": {{API/Widget/Dashboard/SDK/Portal}},
        "entity": {{Data/Insight/Verification/Payment}}
   },
   error: null
}

Field description

Field	Description
status	HTTP/HTTPS status code
message	Text message
data	Response data
source	It defines from where APIs request is coming, It can be either one from API, Widget, Dashabord, SDK or Portal.
entity	It defines which product the APIs request is coming from, It can be either one from Data, Insight, Verification, or Payments.
error	In case of success, error will be null

---

Error Response

Sample of error response

Code
{
           "status" : XXX,
           “error”:{
                  "code": {{brick_unique_error_code}},
                  "message": {{description_of_error}},
                  "action": {{further_action}},
                  "reason": {{Actual_reason_for_error}}
          },
          “metadata”:{
                  "source": {{API/Widget/Dashboard/SDK/Portal}},
                  "entity": {{Auth/Insight/Verification/Payment}}
         },
         data:null
 }

Field description

Field	Description
status	HTTP/HTTPS status code
code	Brick customized status code
message	Text message
action	Further action to prevent this error
source	It defines from where APIs request is coming, It can be either one from API, Widget, Dashabord, SDK or Portal.
entity	It defines which product the APIs request is coming from, It can be either one from Data, Insight, Verification, or Payments.
error	In case of success, error will be null

You can refer all possible error code in the error handling section.

---