Contact list¶

Contact lists allow you to store a group of contacts that share a common characteristic.

The data is dynamic, and the client can store any field associated with the contacts. It is required to include at least one field for phone or one field for email.

The following sections describe the endpoints related to contact lists.

Before you begin¶

Obtain the Bearer token used by this API. For updates, retain the list identifier UUID-cl; for an individual contact, also retain UUID-contact.

Prepare CSV/XLSX data with at least one phone or email column. Match each column to its data type and mapping; names in examples are not universal fields for every list.

Choose an operation¶

Task	Method and relative path
Create a list from a file	`POST /contact-list/upload`
Load data into an existing list	`PUT /contact-list/{UUID-cl}/upload`
List or retrieve lists	`GET /contact-list` or `GET /contact-list/{UUID-cl}`
Update list name or description	`PUT /contact-list/{UUID-cl}`
Read or add contacts	`GET` or `POST /contact-list/{UUID-cl}/contact`
Update or delete an individual contact	`PATCH` or `DELETE /contact-list/{UUID-cl}/contact/{UUID-contact}`
Delete a list	`DELETE /contact-list/{UUID-cl}`

Use the full URL shown in each section. Deleting a contact and deleting an entire list are separate operations.

Contact list¶

Create contact list from a file¶

POST https://api.obmessage.ai/api/v1/contact-list/upload
Authorization: Bearer {{JWT_TOKEN}}

{
    "params": {
        "skip_row_with_error": true
    },
    "info": {
        "name": "string",
        "description": "string",
        "has_header": true,
        "sheet": "string",
        "encoding": "string",
        "config": {
            "columns": [
                {
                    "index": 0,
                    "source_name": "string",
                    "target_name": "string",
                    "display_name": "string",
                    "order": 1,
                    "type": "string"
                }
            ]
        }
    }
}

This endpoint reads .csv or .xlsx files in column format from 0 to n.

For example, you can create a contact list called datos de prueba using the first column of the filename.csv file and assign that column the name name.

The table below describes list metadata. Fields such as name, has_header, and config belong inside info, as shown in the JSON structure; params is a separate object.

Field	Description	Required
params	Additional upload parameters.	No
params.skip_row_with_error	Indicates whether rows with errors should be skipped during contact list upload.	No
name	Contact list name.	No
description	Contact list description.	No
has_header	Indicates whether the file data contains a header row.	Yes
sheet	Sheet to process in `.xlsx` files.	No
encoding	File encoding. Applies only to `.csv` files.	No
config	Configuration of the columns contained in the contact list.	Yes
config.columns.id	Column identification code in the contact list.	Yes
config.columns.index	Column index in the file, from `0` to `n`. If the list has more than one column, this field is required.	Yes
config.columns.type	Column data type. See Data types.	Yes
config.columns.order	Column order or priority. If the list has more than one column, this field is required.	Yes
config.columns.source_name	Column name when the file contains headers.	No
config.columns.target_name	Name assigned to the column.	Yes
config.columns.display_name	Friendly column name.	No

Data types¶

The supported data types are described below:

Data type	Description
text	Variable-length string of letters, numbers, and special characters. Maximum length: 255.
integer	Signed integer.
decimal	Fixed-point decimal number with precision `(18, 2)`.
phone	Phone number compatible with the E.164 recommendation.
email	Email address.
date	Date in `YYYY-MM-DD` format.
time	Time in `HH:mm:ss` format.
datetime	Date and time in `YYYY-MM-DD HH:mm:ss` format.

Note

All data types are validated according to these specifications when creating or updating the contact list.

Try it in Postman

Update contact list data from a file¶

PUT https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/upload
Authorization: Bearer {{JWT_TOKEN}}

{
    "params": {
        "append": true,
        "skip_row_with_error": true
    }
}

UUID-cl: contact list ID.

Try it in Postman

This endpoint updates contact list data from a file.

Upload parameter	Description
params.append	Indicates whether an append should be performed on the contact list. For more information about append, see this link.
params.skip_row_with_error	Indicates whether rows with errors should be skipped during contact list upload.

Query contact lists¶

GET https://api.obmessage.ai/api/v1/contact-list
Authorization: Bearer {{JWT_TOKEN}}

This endpoint allows you to view existing contact lists. The result is returned as paginated contact lists.

This endpoint supports the following parameters or filters:

Field	Description
id	Contact list identification code.
name	Contact list name.
current_page	Page to retrieve.
items_per_page	Maximum number of items per page.
desc	Pagination order. Default is `asc`.

Sample response: 200 OK

{
    "current_page": 1,
    "items_per_page": 5,
    "items": [
        {
            "id": "ece619cb-605e-4150-be72-3f3b920e0bd7",
            "name": "test",
            "description": "test",
            "has_header": true,
            "encoding": "",
            "sheet": "",
            "created_at": "2022-10-31T14:33:17.434Z"
        }
    ]
}

Try it in Postman

Query a contact list by ID¶

GET https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}
Authorization: Bearer {{JWT_TOKEN}}

UUID-cl: contact list ID.

Sample response: 200 OK

{
    "id": "73143085-198c-4538-941b-45517077de67",
    "name": "test",
    "description": "test",
    "has_header": true,
    "encoding": "",
    "sheet": "",
    "created_at": "2022-10-31T14:33:17.434Z",
    "updated_at": "2022-10-31T15:38:43.765Z",
    "config": {
        "columns": [
            {
                "id": "14af0d04-715b-432e-9550-a5736acf468c",
                "index": 0,
                "type": "text",
                "order": 1,
                "source_name": "test",
                "target_name": "test",
                "display_name": "test"
            }
        ]
    }
}

Update a contact list¶

PUT https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

UUID-cl: contact list ID.

Try it in Postman

This endpoint updates a contact list by its ID.

Only the following fields can be updated:

name
description

Note

Returns the contact list in JSON format.

Delete a contact list¶

DELETE https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}
Authorization: Bearer {{JWT_TOKEN}}

Try it in Postman

Deletes a contact list by its ID.

Contact¶

Query contacts from a list¶

GET https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact
Authorization: Bearer {{JWT_TOKEN}}

Try it in Postman

UUID-cl: contact list ID.

This endpoint allows you to view the data of a specific contact list. The result is returned as paginated contacts with dynamic data.

This endpoint supports the following parameters or filters:

Field	Description
pk_id	Contact identification code.
current_page	Page to retrieve.
items_per_page	Maximum number of items per page.
desc	Pagination order. Default is `asc`.

Sample response: 200 OK

{
    "current_page": 1,
    "items_per_page": 10,
    "items": [
        {
            "contact_id": "71088a9d-7aa3-4736-8e17-383a4a567b9b",
            "id": 1,
            "nombre": "juan perez",
            "telefono": "+18099999999",
            "email": "test@test.com",
            "columna1": "1",
            "columna2": "2"
        }
    ]
}

Query a contact by ID¶

GET https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact/{UUID-contact}
Authorization: Bearer {{JWT_TOKEN}}

Try it in Postman

This endpoint retrieves a specific contact by its ID.

Field	Description
UUID-cl	Contact list ID.
UUID-contact	Contact ID.

Sample response: 200 OK

{
    "contact_id": "71088a9d-7aa3-4736-8e17-383a4a567b9b",
    "id": 1,
    "nombre": "juan perez",
    "telefono": "+18099999999",
    "email": "test@correo.com",
    "columna1": "1",
    "columna2": "2"
}

Add a new contact¶

POST https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

Try it in Postman

This endpoint adds a new contact to a specific contact list.

Field	Description
UUID-cl	Contact list ID.

It receives a JSON payload with the new contact data. For example:

{
    "name": "juan perez",
    "tel": "+18099999999"
}

Partially update a contact¶

PATCH https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact/{UUID-contact}
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

Try it in Postman

Partially updates a contact from a specific contact list.

Field	Description
UUID-cl	Contact list ID.
UUID-contact	Contact ID.

For example:

{
    "name": "Juan Perez",
    "phone": "+18099999999"
}

Delete a contact¶

DELETE https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact/{UUID-contact}
Authorization: Bearer {{JWT_TOKEN}}

Try it in Postman

Deletes a contact from a specific contact list.

Field	Description
UUID-cl	Contact list ID.
UUID-contact	Contact ID.

Check the result¶

After creating or updating a list, query it by ID and review its contacts. Match the columns and values to the input data. When uploading with skipped errors, check the upload history before using the audience.

The upload JSON describes metadata, not the CSV/XLSX file itself. Use the upload configuration provided for your integration; if the file attachment format is unclear, obtain it from support before implementing the request.