Please make sure you read the Conventions before continuing with this guide.
Prerequisites
You will need an X-API-KEY and a Basic Access Authentication token generated from your username and password.
How to know if I can use a people lookup
When working on the sales flow, if the selected product contains a property named dynamicFormId, and this property exists with a value other than null, it indicates that the product can utilize a dynamic form to request information about an individual. If the product is linked to a dynamic form with people lookup enabled, it enables you to enhance the amount of information associated with each person and facilitates easy pre-population of form data based on previous interactions.
Using people lookup
GET
Initially, attempt to retrieve a person's data from the People Lookup collection for each passenger (or sender/receiver).
You can get the peopleLookup record using the /accounts/people-lookups endpoint with the dynamicFormId of the product.
Example request:
GET /accounts/people-lookups?documentTypeId={documentTypeId}&documentNumber={documentNumber}&dynamicFormId={dynamicFormId}
Replace {documentTypeId}, {documentNumber}, and {dynamicFormId} with the actual values you have for each passenger or sender/receiver.
Make sure to include the appropriate authorization headers and any other required headers specified by the API documentation.
If this person has data associated with `this particular dynamic form`, the response will resemble the following:
PEOPLE LOOKUP - GET - RESPONSE
{
"people": [
{
"accountId": "yourAccountId",
"documentTypeId": "63a4648ce4456d3b64b2e0ac",
"documentNumber": "1234567",
"firstName": "Robert",
"lastName": "Smith",
"fullName": "Robert Smith ",
"email": "robert@mail.com",
"phone": "4321",
"dynamicForms": {
"646cdc7b6cfe8c06570b164f": {
"documentType": "63a4648ce4456d3b64b2e0ac",
"documentNumber": "1234567",
"firstName": "Robert",
"lastName": "Smith",
"gender": "M",
"phone": "1234",
"email": "robert.smith@mail.com"
}
},
"_id": "650c8abedb84e1051eb5d6e8",
"createdBy": "5b9fb96e58ba02521e0004cd",
"updatedBy": "5b9fb96e58ba02521e0004cd",
"createdAt": {
"value": "2023-09-21T18:26:06.798Z",
"offset": 0
},
"updatedAt": {
"value": "2024-01-04T14:28:59.032Z",
"offset": 0
}
}
],
"next": "",
"previous": "",
"count": 1
}
As you can observe, you can retrieve the data associated with the dynamic form, along with the top-level information already mapped to standard Betterez fields.
The top-level information is obtained by mapping the custom fields from the most recent POST/PUT request to People Lookup.
If there is no person linked to this dynamic form, you will receive an empty array:
{
"people": [],
"next": "",
"previous": "",
"count": 0
}
POST
If the person doesn't exist or doesn't have data associated with this dynamic form, you must complete the required data and make a POST request to save it in the collection. Make sure the properties match with the custom fields form the dynamicForm
POST /accounts/people-lookups
PEOPLE LOOKUP - POST - REQUEST
{
"dynamicForms": {
"dynamicFormId": {
"firstName": "Robert",
"lastName": "Smith",
"email": "robert@mail.com",
"documentType": "someDocumentTypeId",
"documentNumber": "1234567"
}
}
}
If successful, the response will look like this:
Notice that the dynamicForms field contains all the dynamic forms associated with their corresponding properties. This can give you a more general view that can help you understand the structure better.
PEOPLE LOOKUP - POST - RESPONSE
{
"person": {
"accountId": "5b9ab527c9a3ce572400043e",
"documentTypeId": "63a4648ce4456d3b64b2e0ac",
"documentNumber": "1234325",
"firstName": "Robert",
"lastName": "Smith",
"fullName": "",
"email": "roberto@mail.om",
"phone": "",
"dynamicForms": {
"64821a01b467650661164b45": {
"firstName": "Robert",
"lastName": "Smith",
"email": "roberto@mail.om",
"documentType": "63a4648ce4456d3b64b2e0ac",
"documentNumber": "1234325"
}
},
"createdBy": "5b9fb96e58ba02521e0004cd",
"updatedBy": "5b9fb96e58ba02521e0004cd",
"createdAt": {
"value": "2024-01-05T21:11:20.239Z",
"offset": 0
},
"updatedAt": {
"value": "2024-01-05T21:11:20.241Z",
"offset": 0
},
"_id": "6598707865ca68051834f340"
}
}
PUT
If the POST option results in a DUPLICATED_PERSON error or if you want to update some information, you can use this endpoint.
In the body, you must include a copy of the entire object with the updated data, rather than just the property containing the data, as it will otherwise overwrite it.
The request should be something like this:
PEOPLE LOOKUP - PUT - REQUEST
PUT /accounts/people-lookups
{
"dynamicForms": {
"dynamicFormId": {
"firstName": "originalPassengerFirstName",
"lastName": "originalPassengerLastName",
"documentType": "originalDocumentTypeIdW",
"documentNumber": "originalDocumentNumber",
"email": "updatedMail@mail.com"
}
}
}
If successful, the response will look similar to the POST response.
In any of the previous cases, make sure to note the People Lookup ID for the next step.
As evident in each response, you have top-level information, alongside data specific to the dynamic form. This is because the people lookup endpoint already handles the mapping and extracts associated values from the custom fields to the standard Betterez fields.
This enables you to utilize the standardized data to proceed with the purchase, so make sure to make a POST/PUT request before continue.