---
title: "Claim handle"
method: POST
path: "/v1/onboarding/handle"
tags: ["Owner"]
---

# Claim handle

`POST /v1/onboarding/handle`

## Request

- Base URL: `https://api.vicem.ai`
- URL: `https://api.vicem.ai/v1/onboarding/handle`
- Auth: HTTP bearer

## Request body

- ClaimHandleWithSignupReq
  - `handle` string
  - `displayName` string, required
  - `timezone` string
  - `attribution` SignupAttribution
    - `src` string
    - `ref` string
    - `via` string
    - `utm` object
      - `source` string
      - `medium` string
      - `campaign` string
      - `content` string
      - `term` string
    - `click` object
      - `kind` string, required
      - `id` string, required
    - `page` string
  - `intent` 'unknown_callers' | 'missed_calls' | 'number_to_give_out' | 'bookings'
  - `languages` OwnerLanguage[]
  - `homeCountry` string
  - `purpose` 'me' | 'someone_i_help'
  - `goals` SetupIntent[]

## Response `200`

OK

- ClaimHandleRes
  - `ok` true, required
  - `handle` string, required

## Other responses

- `400`: Invalid request (body not JSON, or schema validation failed).
- `401`: Missing, expired or invalid bearer token.
- `413`: Body over the limit (64 KB; 512 KB for contact import).
- `500`: Unexpected server error (reported to Sentry).

---

[API](https://skmtc.dev/vicem/apis/vicem-api.md) · [All operations](https://skmtc.dev/vicem/apis/vicem-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vicem/apis/vicem-api/revisions/9efcec07e5f4?raw)