---
title: "Claim an unresolved contact address (service agent)"
method: POST
path: "/service_agents/contact_addresses/{id}/claim"
tags: ["ServiceAgent"]
---

# Claim an unresolved contact address (service agent)

`POST /service_agents/contact_addresses/{id}/claim`

## Request

- Base URL: `https://api.voipbin.net/v1.0`
- URL: `https://api.voipbin.net/v1.0/service_agents/contact_addresses/{id}/claim`
- Auth: none declared

Attaches a currently-unresolved contact address (contact_id is NULL) to the given contact, as a service agent. Idempotent if already claimed by the same contact; returns 409 if claimed by a different contact.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `contact_id` string, uuid, required

## Response `200`

Address claimed successfully.

- ContactManagerAddress: Contains source or destination detail info.
  - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session': Type of address.
  - `target` string: The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
  - `target_name` string: Address's name.
  - `name` string: Optional label for this address.
  - `detail` string: Additional notes about this address.
  - `id` string, uuid: Unique identifier for the address.
  - `contact_id` string, uuid: Unique identifier of the contact this address belongs to.
  - `customer_id` string, uuid: Unique identifier of the customer this address belongs to.
  - `is_primary` boolean: Indicates if this is the primary address for the given type.
  - `tm_create` string, date-time: Timestamp when the address was created.

## Other responses

- `400`: Invalid request (INVALID_ARGUMENT).
- `401`: Authentication required (UNAUTHENTICATED).
- `403`: Insufficient permission (PERMISSION_DENIED).
- `404`: Resource not found (NOT_FOUND).
- `409`: State conflict (ALREADY_EXISTS or FAILED_PRECONDITION).
- `500`: Internal error (INTERNAL).

## Changes

- **2026-07-26** `d5569b315411`: 1 warning
  - added the new `web_session` enum value to the `allOf[#/components/schemas/CommonAddress]/type` response property for the response status `200`
- **2026-07-01** `505b7c32e910`: 1 info
  - endpoint added
- **2026-05-30** `995c56ba9219`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/service_agents/contact_addresses/:id/claim/post.md)

---

[API](https://skmtc.dev/voipbin/apis/voipbin-api.md) - [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/11338be3ceae?raw)