HydraCore
API by router

Customer identities

Lookup Identity

Reverse lookup: find which customer owns a given channel identity.

Used by the agent runtime to resolve "who is Telegram user 12345?" before enriching the conversation context.

"Say my name." — Walter White, Breaking Bad

GET
/v1/customers/lookup/identity

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

channelChannel

Channel type

external_idExternal Id

External ID to look up

instance_id?Instance Id

Optional instance scope

Header Parameters

X-Api-Key?X-Api-Key

Response Body

curl -X GET "https://loading/v1/customers/lookup/identity?channel=string&external_id=string&instance_id=497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "X-Api-Key: string"
{
  "channel": "string",
  "customer_email": "string",
  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  "display_name": "string",
  "external_id": "string",
  "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1",
  "role_override": "string",
  "verified": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

List Customer Identities

List all external identities linked to a customer.

"I'm Batman." — Batman (about identity, obviously)

GET
/v1/customers/{customer_id}/identities

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

customer_idCustomer Id
Formatuuid

Query Parameters

channel?Channel

Filter by channel

Header Parameters

X-Api-Key?X-Api-Key

Response Body

curl -X GET "https://loading/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08/identities?channel=string" \  -H "X-Api-Key: string"
[
  {
    "channel": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
    "display_name": "string",
    "external_id": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
    "metadata": {},
    "role_override": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "verified": true,
    "verified_at": "2019-08-24T14:15:22Z"
  }
]
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Create Customer Identity

Link an external channel identity to a customer.

"We can do this the easy way, or the hard way." — every cop movie ever

POST
/v1/customers/{customer_id}/identities

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

customer_idCustomer Id
Formatuuid

Header Parameters

X-Api-Key?X-Api-Key

Request Body

channelChannel

Channel type: telegram, whatsapp, slack, etc.

display_name?Display Name
external_idExternal Id

External ID (chat_id, phone, etc.)

Length1 <= length <= 255
instance_id?Instance Id

Optional: scope to a specific instance

metadata?Metadata
role_override?Role Override

Override channel default role: 'owner' for elevated access, null for default

Response Body

curl -X POST "https://loading/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08/identities" \  -H "X-Api-Key: string" \  -H "Content-Type: application/json" \  -d '{    "channel": "string",    "external_id": "string"  }'
{
  "channel": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  "display_name": "string",
  "external_id": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "metadata": {},
  "role_override": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "verified": true,
  "verified_at": "2019-08-24T14:15:22Z"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Update Customer Identity

Update an identity link (display name, verification status, metadata).

"I've made a huge mistake." — Gob Bluth, Arrested Development (about linking the wrong Telegram to the wrong customer)

PATCH
/v1/customers/{customer_id}/identities/{identity_id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

customer_idCustomer Id
Formatuuid
identity_idIdentity Id
Formatuuid

Header Parameters

X-Api-Key?X-Api-Key

Request Body

display_name?Display Name
metadata?Metadata
role_override?Role Override
verified?Verified

Response Body

curl -X PATCH "https://loading/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08/identities/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "X-Api-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "channel": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  "display_name": "string",
  "external_id": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "metadata": {},
  "role_override": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "verified": true,
  "verified_at": "2019-08-24T14:15:22Z"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Delete Customer Identity

Unlink an external identity from a customer.

"Forget about it, Jake. It's Chinatown." — Walsh, Chinatown

DELETE
/v1/customers/{customer_id}/identities/{identity_id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

customer_idCustomer Id
Formatuuid
identity_idIdentity Id
Formatuuid

Header Parameters

X-Api-Key?X-Api-Key

Response Body

curl -X DELETE "https://loading/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08/identities/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "X-Api-Key: string"
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Generate Identity Claim Code

Generate a one-time claim code for an unverified identity.

Matt clicks "Generate Code" in the dashboard, reads the 6-char code to Steve, Steve types /claim CODE in Telegram, platform verifies and marks identity as verified + owner.

"The code is... one, two, three, four, five. That's the stupidest combination I've ever heard in my life!" — Dark Helmet, Spaceballs (Our codes are considerably better than that.)

POST
/v1/customers/{customer_id}/identities/{identity_id}/claim-code

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

customer_idCustomer Id
Formatuuid
identity_idIdentity Id
Formatuuid

Header Parameters

X-Api-Key?X-Api-Key

Response Body

curl -X POST "https://loading/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08/identities/497f6eca-6276-4993-bfeb-53cbbbba6f08/claim-code" \  -H "X-Api-Key: string"
{
  "code": "string",
  "expires_in_seconds": 900,
  "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1",
  "instructions": "string"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Customer auth

Previous Page

Customer signup

Next Page