Using Idempotent Identifiers to Manage Customers

This guide explains how to use the Idempotent Identifier — your own internal reference for a Customer — when creating, retrieving, and deleting Customers, and when making calls to other Bud APIs on behalf of a Customer.

If you haven't set up Customers yet, start with Setup your Customers first.

What is an Idempotent Identifier?

When you create a Customer in Bud, you can supply your own identifier via the client_metadata.idempotent_identifier field. Bud will store this alongside the Bud-generated customer_id (a UUID) and guarantee that calling POST platform/v3/customers with the same idempotent_identifier more than once will always return the same Customer entity — never create a duplicate.

This is useful when:

• You want to reference a Customer across Bud APIs using your own identifier rather than storing and managing the Bud customer_id.
• You want to tie a Bud Customer directly to a user record in your own system (e.g. your internal user ID).
• You need to make Customer creation calls idempotent in retry scenarios.

👍

Recommended practice

Use a stable, unique identifier from your own system (such as a user ID or account reference) as the idempotent_identifier. This lets you skip any need to persist or look up the Bud customer_id on your side.

⚠️

Do not use sensitive personal data — such as a National Insurance number, Social Security number, date of birth, or email address — as the idempotent_identifier. This value appears in API paths and headers and should be an opaque internal reference, not personal information.

Creating a Customer with an Idempotent Identifier

Include idempotent_identifier inside the client_metadata object when calling POST platform/v3/customers.

Example request:

curl --request POST \
  --url https://api-sandbox.thisisbud.com/platform/v3/customers \
  --header 'Authorization: Bearer <your_token>' \
  --header 'X-Client-Id: <your_client_id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_metadata": {
      "idempotent_identifier": "your-internal-user-id-123"
    }
  }'

• A 201 Created response means a new Customer was created.
• A 200 OK response means a Customer with that idempotent_identifier already existed — the same Customer is returned, and no duplicate is created.

Example response:

{
  "operation_id": "platform_v3_customers_post",
  "data": {
    "customer_id": "acbff0b9-299c-4065-b933-4a991e17da6d",
    "customer_context": {
      "type": "personal",
      "region": "US",
      "locale": "en-US"
    },
    "client_metadata": {
      "idempotent_identifier": "your-internal-user-id-123"
    }
  },
  "metadata": {
    "created_at": "2024-01-15T10:30:00+0000"
  }
}

Retrieving a Customer by Idempotent Identifier

You can use the idempotent_identifier query parameter on GET platform/v3/customers to look up a specific Customer without needing to know their Bud customer_id.

Example request:

curl --request GET \
  --url 'https://api-sandbox.thisisbud.com/platform/v3/customers?idempotent_identifier=your-internal-user-id-123' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'X-Client-Id: <your_client_id>'

Example response:

{
  "operation_id": "platform_v3_customers_get",
  "data": [
    {
      "customer_id": "acbff0b9-299c-4065-b933-4a991e17da6d",
      "idempotent_identifier": "your-internal-user-id-123",
      "created_at": "2024-01-15T10:30:00+0000"
    }
  ],
  "metadata": {
    "results": 1
  }
}

Using the Idempotent Identifier Across Bud APIs

Once a Customer has an idempotent_identifier, you can use it as a header in place of X-Customer-Id whenever you call any Bud API endpoint that operates on behalf of a Customer.

Pass it using the X-Customer-Idempotent-Identifier header:

These two headers are mutually exclusive — use one or the other per request.

Example — retrieving a Customer's accounts using the Idempotent Identifier:

curl --request GET \
  --url https://api-sandbox.thisisbud.com/financial/v3/accounts \
  --header 'Authorization: Bearer <your_token>' \
  --header 'X-Client-Id: <your_client_id>' \
  --header 'X-Customer-Idempotent-Identifier: your-internal-user-id-123'

Example — retrieving a Customer's transactions using the Idempotent Identifier:

curl --request GET \
  --url https://api-sandbox.thisisbud.com/financial/v3/transactions \
  --header 'Authorization: Bearer <your_token>' \
  --header 'X-Client-Id: <your_client_id>' \
  --header 'X-Customer-Idempotent-Identifier: your-internal-user-id-123'

👍

Tip

Using X-Customer-Idempotent-Identifier consistently means your integration never needs to store or manage Bud's customer_id — your own user identifier is sufficient to interact with all Bud APIs.

Deleting a Customer by Idempotent Identifier

To delete a Customer using their idempotent_identifier, call DELETE platform/v3/customers/idempotent-identifier/{customer_idempotent_identifier}.

Example request:

curl --request DELETE \
  --url https://api-sandbox.thisisbud.com/platform/v3/customers/idempotent-identifier/your-internal-user-id-123 \
  --header 'Authorization: Bearer <your_token>' \
  --header 'X-Client-Id: <your_client_id>'

A 202 Accepted response confirms the deletion has been initiated. All data associated with the Customer will be removed asynchronously.

❗️

Deletion is permanent

Deleting a Customer removes all associated data. This action cannot be undone. Once deletion is complete, the idempotent_identifier is released — calling POST platform/v3/customers with the same identifier will create a fresh Customer with no connection to the previous one.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.