End Users

An end user is your user — the recipient of your utility messages, identified by your own customerUserId. These endpoints bind that ID to an eligible phone number and let your backend look the binding up later.

Signing is the anti-enumeration control

While request signing is enabled (the default), both endpoints run under the pipeline's request signing: only a caller holding your signing secret can probe which numbers are bound and eligible.

Why bind end users

Sends accept an optional customerUserId that is echoed back and recorded with each message — binding makes that association first-class. Bind once at signup or verification, then:

Look up by customerUserId before a send to confirm the user has an eligible number on file, then deliver with the Send API.
Look up by phone number to find which of your users it belongs to when processing delivery outcomes.

Binding is tenant-scoped: you only ever see your own bindings.

Bind an end user

Associates a customerUserId with a phone number. The number must already be eligible — binding does not grant eligibility, so an attacker cannot bootstrap it by binding arbitrary numbers.

A user can hold multiple numbers: binding a second number to the same customerUserId adds it. Re-binding an existing pair refreshes its eligibility label.

Body

Name
APIKey
Type
string
Description
Your account API key.
Name
pipelineID
Type
string
Description
A utility pipeline on your account. Used to authenticate and to check eligibility.
Name
customerUserId
Type
string
Description
Your internal ID for the user.
Name
phone
Type
string
Description
The user's phone number, E.164. Canonicalized before binding.

Response fields

Name
customerUserId
Type
string
Description
The bound ID.
Name
phone
Type
string
Description
The canonical E.164 form that was bound.
Name
eligibility
Type
string
Description
The proof the number passed with: verified or allowlist.

Request

POST

https://api.akedly.io/api/v1/utilities/end-users

{
  "APIKey": "<AKEDLY_API_KEY>",
  "pipelineID": "<YOUR_PIPELINE_ID>",
  "customerUserId": "user_123",
  "phone": "+201234567890"
}

Response

JSON

200 Status

{
  "status": "success",
  "data": {
    "customerUserId": "user_123",
    "phone": "+201234567890",
    "eligibility": "allowlist"
  }
}

Look up an end user

Finds a binding by either key. Provide customerUserId to check whether that user has a bound number, or phone to find which user a number belongs to. When both are present, customerUserId wins.

An unknown key is not an error — the call succeeds with bound: false.