Skip to main content
Deprecated: The “Contacts” feature has been deprecated in favor of Identities. If you’re currently using Contacts, please migrate to Identities for continued support and access to new features. See the API reference for implementation details.
Identities are an entity used to tie metrics within the orq.ai APIs. They can represent:
  • a User
  • a Team
  • a Project
  • a Client
Identities are Created through the API and then are used as supplementary data to store Identity Metrics within any other call of the API.

​
Creating an identity using the Studio

To create an Identity, head to the Identity Analytics section and choose Create an Identity. The following panel opens:

​
Budget Control

When creating an identity, set a Budget in order to:
  • Prevent individual users from exceeding the allocated AI budget
  • Set department-level spending limits for the enterprise team
  • Control costs across multiple AI models and services
Each budget has a period and an amount (in USD). When the identity’s spend reaches the limit within the period, subsequent requests are blocked with a 429 Too Many Requests response until the period resets. The available periods are Daily, Weekly, Monthly, and Yearly.

​
Creating an identity using the API

To create an identity, you have two options:
  1. Use the API directly: You can create an Identity with the cURL code snippet.
  2. SDK Implementation: (Recommended) The SDK provides a more streamlined approach to creating Identities.

curl --location 'https://api.orq.ai/v2/identities' \
--header 'Authorization: Bearer <your-api-key>:' \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "1234",
    "display_name": "Client A",
    "email": "[email protected]",
    "avatar_url": "https://gravatar.com/avatar/6c568aaa96fdbd3e466b500e6eb312dc?s=400&d=robohash&r=x",
    "metadata": {
      "role": "admin"
    }
}'
Developers, please see the API Reference for further explanation.

​
Using Identity metrics

To track Identity metrics effectively, you have two primary options:
  1. API Direct Usage: When using the API directly, you can attach the identity ID through the request headers.
  2. SDK Implementation: We strongly recommend using our SDKs, as they provide a more streamlined approach to tracking identity metrics.
curl 'https://api.orq.ai/v2/deployments/invoke' \
-H 'Authorization: Bearer {apiKey}' \
-H 'X-ORQ-IDENTITY-ID: <external_id>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
   "key": "<deployment_key>",
   "context": {
      "environments": []
   }
}' \
--compressed
To learn more, see the API Reference.