Profile

Operations tagged Profile in the public API.

About Profile

The profile is the account owner's contact details: name, company, website, job_title, country_code and a free-text phone. It belongs to the account owner, not to whoever minted the key, so PATCH /me/profile changes what the owner sees in the dashboard. Email cannot be changed through the API.

profile:write is high-risk. Only the account owner can grant it when minting a key, it is confirmed on its own (a "select all" never includes it), and a dashboard personal access token never carries it. Every successful PATCH /me/profile emits profile.updated.

Phone. phone is display-only text. The number the account verified by SMS at signup is never returned or changed here; phone_verified only says whether that verification happened.

IDs you will meet.

id — the account id, the same value as id on GET /me. No operation takes it.

/v1/me/profile

Retrieve the account profile

Returns the account owner's contact details — the owner's, not those of whoever minted the key. phone is display-only contact text: it is never verified and never used to sign in or to pass the phone-verification gate. phone_verified (read-only) says whether the account completed SMS verification of its signup number, which this API neither shows nor changes.

Required scope: profile:read
Idempotency: Read-only
Rate limits

Responses

200
Success.
objectstringRequired
Alwaysprofile
idintegerRequired
The account id, the same value as id on GET /me.
namestringRequired
The account owner's display name.
companystringnullableRequired
Company name; null when unset.
websitestringnullableRequired
Website URL; null when unset.
job_titlestringnullableRequired
Job title; null when unset.
country_codestringnullableRequired
ISO 3166-1 alpha-2 country code, upper case; null when unset.
phonestringnullableRequired
Display-only contact phone, free text. Never verified and never the number the account signed up with.
phone_verifiedbooleanRequired
Whether the account verified its signup phone number by SMS. Read-only: that number is neither shown nor changed by the API.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/me/profile' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "profile",
  "id": 1,
  "name": "Acme Support",
  "company": "Acme Retail",
  "website": "https://acme.example.com",
  "job_title": "Support Lead",
  "country_code": "GB",
  "phone": "+44 20 7183 8750",
  "phone_verified": false
}

/v1/me/profile

Update the account profile

Changes the account owner's contact details and returns the profile. name is required on every call — send the current one to change only other fields; an optional field you leave out is unchanged, and a blank or null one is cleared. Every successful call emits profile.updated, even one that changes nothing. Writing phone changes the display-only contact text; it does not touch the verified signup number and leaves phone_verified unchanged.

Required scope: profile:write
Idempotency: Accepts Idempotency-Key
Webhook events: profile.updated
Rate limits

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Public /v1 update profile payload. Field set is pinned on this class so a dashboard FormRequest tweak cannot silently widen the public contract.

namestringRequired
The account owner's display name, 1–40 characters, trimmed. Required on every call: send the current name to change only other fields.
Min length: 1Max length: 40
companystringnullableOptional
Company name, at most 120 characters. Blank or null clears it.
Max length: 120
websitestringnullableOptional
Website: an http or https URL of at most 255 characters. Blank or null clears it.
Format: uriMax length: 255
job_titlestringnullableOptional
Job title, at most 120 characters. Blank or null clears it.
Max length: 120
country_codestringnullableOptional
ISO 3166-1 alpha-2 country code, any case (gb is stored as GB); a code that is not a country is 422. A code also replaces country; blank or null clears the code and leaves country as it was.
Min length: 2Max length: 2
countrystringnullableOptional
Legacy free-text country, at most 120 characters; the profile does not return it. Prefer country_code. Overwritten by country_code when the same request sends a code.
Max length: 120
phonestringnullableOptional
Display-only contact phone (free text, max 32 characters). Not verified, not the signup number, never an identity; phone_verified on the profile is unaffected.
Max length: 32

Responses

200
Success.
objectstringRequired
Alwaysprofile
idintegerRequired
The account id, the same value as id on GET /me.
namestringRequired
The account owner's display name.
companystringnullableRequired
Company name; null when unset.
websitestringnullableRequired
Website URL; null when unset.
job_titlestringnullableRequired
Job title; null when unset.
country_codestringnullableRequired
ISO 3166-1 alpha-2 country code, upper case; null when unset.
phonestringnullableRequired
Display-only contact phone, free text. Never verified and never the number the account signed up with.
phone_verifiedbooleanRequired
Whether the account verified its signup phone number by SMS. Read-only: that number is neither shown nor changed by the API.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PATCH 'https://api.agentency.com/v1/me/profile' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "name": "name",
  "company": "company",
  "website": "website",
  "job_title": "job_title",
  "country_code": "country_code",
  "country": "country",
  "phone": "phone"
}'

Response

Example 200 response

json

{
  "object": "profile",
  "id": 1,
  "name": "Acme Support",
  "company": "Acme Retail Ltd",
  "website": "https://acme.example.com",
  "job_title": "Head of Customer Support",
  "country_code": "GB",
  "phone": "+44 20 7183 8750",
  "phone_verified": false
}

About Profile

Phone. phone is display-only text. The number the account verified by SMS at signup is never returned or changed here; phone_verified only says whether that verification happened.

IDs you will meet.

id — the account id, the same value as id on GET /me. No operation takes it.

{ "object": "profile", "id": 1, "name": "Acme Support", "company": "Acme Retail", "website": "https://acme.example.com", "job_title": "Support Lead", "country_code": "GB", "phone": "+44 20 7183 8750", "phone_verified": false }

curl -X PATCH 'https://api.agentency.com/v1/me/profile' \ -H "Authorization: Bearer <YOUR_KEY>" \ -H "Content-Type: application/json" -d '{ "name": "name", "company": "company", "website": "website", "job_title": "job_title", "country_code": "country_code", "country": "country", "phone": "phone" }'

{ "object": "profile", "id": 1, "name": "Acme Support", "company": "Acme Retail Ltd", "website": "https://acme.example.com", "job_title": "Head of Customer Support", "country_code": "GB", "phone": "+44 20 7183 8750", "phone_verified": false }

Profile

About Profile

/v1/me/profile

Responses

See also

Request

Response

/v1/me/profile

Header parameters

Request body

Responses

See also

Request

Response

Profile

About Profile

/v1/me/profile

Responses

See also

Request

Response

/v1/me/profile

Header parameters

Request body

Responses

See also

Request

Response