How to use the Papo API to manage contacts' custom attributes

To manage contacts' custom attributes programmatically, use the Papo REST API. With secret key authentication, you can list attribute definitions, create new custom fields, and set or merge values on contacts — ideal for syncing data from external CRMs, enriching profiles, and refining campaign and automation segmentation without manual intervention.

The Papo API exposes specific resources for custom attributes, allowing your operation to keep a contact base always up to date with relevant business information. Whether importing data from an ERP, migrating lists from a legacy CRM, or automating lead classification, these endpoints work with the same simple authentication as the platform's other resources.

Summary of the integration process

How it works: step by step

1. Authentication and keys

Every call that modifies data requires the account's secret key, sent as a Bearer token in the Authorization header. The public key (fixed per account) can accompany the request in the X-Papo-Public-Key header — its use is optional, but if sent it must match the same account as the secret key. The API base URL is https://app.papo.global/api/v1. Keys are generated in the developer area of the Papo dashboard.

2. Manage attribute definitions

Before populating values, the attribute definition must exist in the account. The API allows you to:

• List all custom attributes already registered, to audit standardization or map fields before an integration.
• Create a new definition, providing:
  • attribute_key — unique identifier (e.g., plan, city).
  • attribute_display_name — readable name that appears in the CRM (e.g., “Contracted Plan”).
  • attribute_model — field type: text, number, date, or list (with predefined options).

These operations are essential to prepare the structure that will receive data from external systems.

3. Set and update values on contacts

With the definitions ready, you can send requests to merge the custom_attributes on a specific contact. The payload includes a key-value object with the attributes you want to update. For example, to set the plan “Pro” and the city “São Paulo” on a contact, the JSON would contain something like {"plan": "Pro", "city": "São Paulo"}. The API processes one contact per request, but bulk operation is achieved by executing multiple calls in sequence — with Python, Node.js scripts, or automations in n8n.

4. Synchronization with external CRM (typical use case)

A script can:

1. Read records from an external CRM, ERP, or database.
2. For each record, map the fields of interest to the corresponding attribute_key values in Papo.
3. If necessary, create the attribute definition (if it does not already exist).
4. Send the contact update request (identified by ID, email, or phone) with the custom_attributes.
5. Collect the responses and handle any errors (invalid field, nonexistent key, etc.).

This way, the Papo base remains a faithful mirror of your ecosystem's data, ready for segmentations and automations.

5. Impact on automations and campaigns

Once the attributes are populated, they are immediately available for:

• Flows with conditions based on contact attributes (e.g., send a specific message to those whose plan equals “Enterprise”).
• Dynamic segments for WhatsApp or email marketing campaigns.
• Reports and filters in the CRM, allowing teams to view and prioritize contacts based on any custom field.

Who this integration is for

• Companies that use multiple systems (CRM, ERP, e-commerce) and need to centralize customer information in Papo without manual data entry.
• Operations migrating from another platform and wanting to import not only contacts but also custom fields such as “lead source,” “score,” or “last purchase.”
• Marketing and sales teams that segment campaigns based on structured data (plan, region, interest) and need that data to always be up to date.
• White label resellers that customize attributes for each end customer and want to automate synchronization from their customers' own systems.

Frequently asked questions

Do I need to create the attribute before setting the value on the contact?

Yes. The attribute definition (with attribute_key, name, and model) must exist in the account. You can create it via the API or in the dashboard under Settings → Custom Attributes.

What types of attributes can I create via the API?

The API supports the same types available in the dashboard: text, number, date, and list (with predefined options). The model is provided in the attribute_model field when creating the definition.

How can I update multiple contacts at once?

The API processes one contact per request. For bulk operations, automate batch sending with scripts (Python, Node.js) or tools such as n8n, iterating over a list of contacts and sending requests sequentially.

Where can I find the exact endpoints and payload format?

In the official API documentation, available at https://papo.global/pt/docs. There you will find detailed custom attribute endpoints, authentication, and code examples.

Can I use the API to clear or remove an attribute from a contact?

The API documentation describes the available operations. For removal or clearing cases, consult the official reference to check whether there are specific endpoints or whether you need to reset the value.

Do attributes updated via the API trigger automations?

Yes. Updating a contact via the API can trigger internal events, such as the execution of Flows configured with triggers related to contact changes, as long as the conditions are met.

Read also

• How to use the Papo API to create and update contacts in bulk
• How to use the Papo API to create and manage tags

Start for free and integrate your data →

With the Papo API, you sync custom attributes in bulk and refine campaign segmentation without leaving your workflow.