Send customer data

Merge semantics

Endear automatically deduplicates customer profiles in the background. The system runs every few hours, so duplicates may appear briefly in the customer list before resolving on their own — no manual action is required.

Records are merged when:

• Email matches — Identical email addresses are the primary signal and always trigger a merge.
• Phone number + name similarity — A matching phone number combined with names that are at least 80% similar will merge profiles even when their email addresses differ.

When two profiles merge:

• All data consolidates into a single profile.
• Transaction history and customer interactions are preserved.
• The most complete profile becomes the primary record.

For duplicates the automated system doesn't catch, customers can also be merged manually in the Endear app. See Understanding Endear's automated customer deduplication process for more detail.

Custom fields

Customers support custom fields keyed by name. Define them either:

• Directly in the Endear app, or
• Programmatically via the createCustomerField mutation.

Once a field is defined, set values on each customer through the custom_fields array on bulkUpsertExternalCustomers.

Push customer records

Example customer records

Let's assume you have customers that look something like this:

Example mutation

You can push these records using any HTTP compatible library:

fetch("https://api.endearhq.com", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-endear-api-key": "{{API_KEY}}",
  },
  body: JSON.stringify({
    query: `
      mutation BulkUpsertExternalCustomers($customers: [ExternalCustomerInput!]!) {
        bulkUpsertExternalCustomers(customers: $customers) {
            status
        }
      }
    `,
    variables: {
      customers: [
      	{
          id: "cust_1",
          first_name: "Jane",
          last_name: "Doe",
          email_address: "[email protected]",
          tags: ["vip"],
          created_at: "2023-04-21T17:08:47Z",
          updated_at: "2023-05-09T11:18:12Z",
          deleted_at: null,
        },
        {
          id: "cust_2",
          first_name: "John",
          last_name: "Doe",
          email_address: "[email protected]",
          tags: [],
          created_at: "2023-04-21T17:08:47Z",
          updated_at: "2023-05-09T11:18:12Z",
          deleted_at: "2023-05-09T11:18:12Z",
        },
        {
          id: "cust_3",
          first_name: null,
          last_name: null,
          email_address: "[email protected]",
          tags: [],
          created_at: "2023-04-21T17:08:47Z",
          updated_at: "2023-05-09T11:18:12Z",
          deleted_at: null,
        }
      ],
    },
  }),
});