Universal Enrichment - API Best Practices for Integration Partners Follow

This guide is for integration partners building or exposing an API endpoint intended to work with Convertr's Universal Enrichment feature. It explains how Universal Enrichment works and sets out best practices for structuring your endpoint so it integrates cleanly.

Universal Enrichment follows a bring-your-own-license model. You can supply valid access keys for the service, and Convertr Customers can configure the integration based on the API documentation and access details provided.

For campaign setup, please go here Universal Enrichment

How Universal Enrichment Works

Universal Enrichment is a feature within a Convertr campaign's processing flow. For each lead submitted to the campaign, Convertr sends a request to your API with selected lead fields, and maps your API's response back onto the lead record.

It can be used to:

• Append missing lead details, such as job title, address, or company revenue
• Append intent data from behavioural or interest-based signals
• Append custom metadata, such as CRM IDs or account tiers
• Validate key lead information using connected validation services

Processing happens one lead at a time, not in batches, and the connection only fails if the connection itself fails (invalid credentials, unreachable endpoint, network error). A successful connection that returns no enrichment data is still treated as a successful job.

Best Practice for Your Endpoint

1. Endpoint basics

• Expose a single-lead POST endpoint over HTTPS with a JSON request and response body.
• Avoid batch-only endpoints. Convertr calls your API once per lead as it processes it, so batch submission models don't fit this flow.
• Only synchronous real-time endpoints are supported - endpoints need to provide required data immediately in the response to the Universal Enrichment request. Async integrations like webhooks or deferred responses aren’t supported.
• The endpoint must respond with all necessary data within 30 seconds.

2. Authentication

Convertr's Universal Enrichment supports three authentication modes. Choose whichever fits your existing infrastructure eg:

POST /v1/enrich HTTP/1.1 Host: api.partner.com Content-Type: application/json Authorization: Bearer <token>

• Headers - Bearer Token, Basic Auth, or an API key header (for example, X-API-Key)
• OAuth - for a client credentials or authorization code flow

If the OAuth token response includes an expiry field (for example expires_in), the field name can be set as the Access Token Expire Key. If the service doesn't return an expiry field, a manual timeout can be configured instead using Access Token Expire In, which applies a default expiry in seconds.

At least one of these two must be configured. If neither is set, Convertr will request a new token for every lead processed, which can quickly exhaust rate limits and cause authentication failures at volume.

3. Request structure

• Flat responses are preferred as it makes connection configuration simpler. However, we fully support nested JSON objects in responses. Convertr supports nested field mapping, so a well-organised request body is easier to configure correctly on our side.
• Keep required fields minimal. Email or domain is usually the safest minimum key to require. Avoid mandating fields that are commonly missing on partial leads, since this increases failed matches rather than genuine connection failures.

4. Response structure

• Always return a 200 with a valid JSON body, even when there is no enrichment data available for that lead. Convertr treats a successful connection as a successful job regardless of data returned, so an empty-but-valid payload is expected behaviour, not an error case.
• Use nested JSON in the response, matching a clear and consistent dot-notation structure (for example person.company.name), so field mapping is straightforward to configure.
• Dynamic keys aren’t supported.
  • For example: {123: “some value”} where “123” is the dynamic value isn’t supported.
  • The supported response structure would be similar to: {“id”: 123, “value”: “some value”}
• Reserve error status codes (4xx or 5xx) for genuine failures only, such as bad authentication, a malformed request, or a service outage. Do not return an error code simply because no match was found for a lead.

Example Payloads

Example request (Convertr to your API)

POST /v1/enrich HTTP/1.1 Host: api.partner.com Content-Type: application/json Authorization: Bearer <token> { "person": { "work_email": "john.doe@example.com", "first_name": "John", "last_name": "Doe" }, "company": { "domain": "example.com" } }

Example response - match found

HTTP/1.1 200 OK Content-Type: application/json { "person": { "job_title": "Marketing Manager", "seniority": "Manager", "company": { "name": "Acme Corp", "revenue": "5000000", "industry": "Software", "address": { "street": "123 Main St", "city": "London", "country": "UK" } } } }

Example response - no match found (still a valid 200)

{ "person": null }

Common Pitfalls to Avoid

• Missing token expiry on OAuth responses, leading to authentication failures at scale
• Returning error codes for "no match found" instead of a valid empty 200, which incorrectly flags jobs as failed in the Processr log
• Flat response structures with ambiguous field names, making response mapping fragile
• Requiring too many fields on the request, reducing match rates for partial leads