Intro

This API allows you to start the execution of a workfloo. It is the first endpoint that you must consume in order to run your origination process.

Important points

To make the request it is only necessary to provide the workfloo ID generated in the workfloo platform.

field	type	required	Description
idWorkflooDefinition	Alphanumeric	Yes	Provide a valid workfloo Id.
scenarioId	Alphanumeric	No	Provide a valid test escenario Id, it is required when the request is applied in sandbox environment.
form	Object	No	To avoid additional API calls for data submission, you can include your form parameters directly within this object.
callbackUrl	Alphanumeric	No	Callbacks URL, for details see callback section.
callbackXApiKey	Alphanumeric	No	Security for your callback

It is mandatory to provide the workfloo identifier as a parameter in JSON request, which you must have created previously. In order to create a workfloo, we recommend you visit our knowledge center.

You can find the ID in the workfloo creation URL, in te ID copy section.

And also in the historic section selection the copy ID button:

In exactly the same way you get the workflow ID, you can get the test scenario ID. Remember that the Sandbox toggle must be active to see this option.

Example of a simple the request body:

{
    "idWorkflooDefinition": "657117e1d511b6e54fe2a967",
    "scenarioId": "6571181fd511b6e54fe2a968"
}

For additional request cases, please refer to the examples provided in the "Requests" section.

Simplify your execution steps

🚧
Avoid the form step
In most cases, the next step after executing the workflow is a form. To reduce the number of APIs to execute, you can submit the form data in this same API. Avoid executing the Execute a Form API.

For example, if your next step is to send the data from a form that queries the credit bureau, the request you would have to send is the following:

{
  "idWorkflooDefinition": "657117e1d511b6e54fe2a967",
  "scenarioId": "6571181fd511b6e54fe2a968",
  "form": {
    "first_name": "FIRST",
    "second_name": "SECOND",
    "last_name_1": "KIBAN",
    "last_name_2": "CLOUD",
    "birth_date": "1990-08-15",
    "rfc_pf": "KIBA801010BPA",
    "address": "AV PASEO DE LA REFORMA 403",
    "postal_code": "06500"
  }
}

This example will execute the workfloo creation process and automatically execute the next step, which is a form. Remember that validations are performed on submitted fields, so they must comply with the rules defined during field creation.

Use callbacks to receive notifications

To receive webhook notifications when your workfloos are executed, include the following fields in the request body:

callbackUrl: the URL of your webhook endpoint where we will send notifications.
callbackXApiKey: (optional) an API key to authorize requests if your webhook is secured.

Notifications will be sent at key points during the workfloo execution:

When the flow is paused and requires your input (e.g., form submission, PIN entry, or document upload).
When the flow has been fully completed.

Below we share some examples of webhooks that you will receive.

PIN

{
  "currentNodeId": "1748283676868449",
  "currentNodeName": "nip",
  "currentNodeType": "LINK",
  "id": "d34d66cd-7995-4d86-b01b-ee576bc70d8d",
  "link": {
    "companyName": "razon",
    "key": "nip",
    "keyTypeNode": "bc_pf_query",
    "phase": ""
  },
  "name": "With callbacks",
  "status": "PROGRESS"
}

Documents

{
  "currentNodeId": "1748283706586301",
  "currentNodeName": "documento",
  "currentNodeType": "DOCUMENT",
  "document": {
    "documentField": [
      {
        "id": "ine_data_extraction_set",
        "name": "Campos INE OCR extracción de datos",
        "predefined": true,
        "required": true,
        "set": {
          "files": [
            {
              "id": "ine_back_image",
              "name": "Imagen trasera de INE",
              "predefined": true,
              "required": true
            },
            {
              "id": "ine_front_image",
              "name": "Imagen frontal de INE",
              "predefined": true,
              "required": true
            }
          ]
        }
      }
    ]
  },
  "id": "d34d66cd-7995-4d86-b01b-ee576bc70d8d",
  "name": "With callbacks",
  "status": "PROGRESS"
}

Form

{
  "currentNodeId": "1748283724487876",
  "currentNodeName": "formulario curp",
  "currentNodeType": "FORM",
  "form": {
    "formFieldSection": [
      {
        "fields": [
          {
            "fieldMetadata": {},
            "id": "curp",
            "name": "CURP",
            "predefined": true,
            "required": false,
            "section": "GENERAL_DATA"
          }
        ],
        "section": "GENERAL_DATA"
      }
    ]
  },
  "id": "d34d66cd-7995-4d86-b01b-ee576bc70d8d",
  "name": "With callbacks",
  "status": "PROGRESS"
}

End of execution

{
  "currentNodeId": "",
  "currentNodeName": "",
  "currentNodeType": "",
  "id": "d34d66cd-7995-4d86-b01b-ee576bc70d8d",
  "name": "With callbacks",
  "status": "SUCCESS"
}

Test the workfloo (Pruebas)

In order to test a workfloo in the sandbox environment, it is necessary that you have previously created a Testing scenario in the workfloo tool for more details see our Knowledge center.

Once you have created your test scenario, you will need to obtain its ID. You should provide this ID in the request body, just like you did to obtain the workflow ID:

From the defined Pruebas URL.
From the edit view of the defined Pruebas.
From the history of Pruebas

Successful response

A successful response will return the execution id of the workfloo, you must save this id, because it will be mandatory to pass it to the following endpoints to complete all the steps defined in your workfloo.

field Name	Description
id	Execution identifier, it will be the data that you must use to execute your next steps in the workfloo

{
    "id": "64a8bc288de4164da93f339c"
}

Listing the possible error responses

Required idWorkflooDefinition

You will get a 400 bad request error when the idWorkflooDefinition is not provided in the request body.

{
    "typeError": "REQUIRED_FIELDS",
    "errors": {
        "idWorkflooDefinition": "required"
    },
    "errorMessage": ""
}

Required scenarioId

You will get a 400 bad request error when the idWorkflooDefinition is not provided in the request body.

{
    "typeError": "ELEMENT_NOT_EXIST_ERROR",
    "errors": null,
    "errorMessage": "scenarioId not found"
}

Does not exits scenarioId

The scenarioId provided does not exist, the service will return the following error 404.

{
    "typeError": "ELEMENT_NOT_EXIST_ERROR",
    "errors": null,
    "errorMessage": "scenarioId not found"
}

Unauthorized

It means that the provided API is incorrect and that you are not authorized to access it. You will not receive a body, only a 401 HTTP code.