> ## Documentation Index > Fetch the complete documentation index at: https://docs.isnap.ai/llms.txt > Use this file to discover all available pages before exploring further. # Issue a BYOD activation code > Issues a single-use activation code, valid for 5 minutes, and the links to the installers of the bridge app. * **Credential:** an API key. * **Account:** a direct account needs a free BYOD slot. A wholesale partner needs none. See [BYOD slots](/guides/byod#byod-slots). * **Line-scoped keys:** the list of lines of a [line-scoped key](/authentication#line-scoped-keys) is not applied. * **Test keys:** a code issued with an `isnap_test_` account key creates a real line: see [Test keys](/authentication#test-keys). * **`Idempotency-Key`:** not honored. A repeated call issues another activation code. See [Operations that honor the key](/idempotency#operations-that-honor-the-key). * **Events:** none. `line.connected` is sent when the user completes the pairing in the bridge app: see [Pairing a device](/guides/byod#pairing-a-device). * **Secret:** `activation_code` is a credential: see [The activation code is a credential](/guides/byod#the-activation-code-is-a-credential). The response carries `Cache-Control: no-store`, whatever its status. ## Errors | Status | `error.code` | When | | - | - | - | | 400 | `validation_failed` | A field other than `metadata`, or a `metadata` over 20 keys or 8,192 bytes. | | 402 | `payment_required` | A direct account with no BYOD slot: see [BYOD slots](/guides/byod#byod-slots). | | 404 | `no_slot_available` | A direct account whose slots are all used by BYOD lines. Terminate a BYOD line to free its slot. | The errors that every operation shares are in [Errors](/errors-and-rate-limits#errors). ## OpenAPI ````yaml POST /v1/byod/pair openapi: 3.0.0 info: title: iSnap API version: 2.45.0 description: >- The iSnap API sends and receives iMessage, RCS and SMS on real phone lines, manages those lines, and reports events through webhooks. Every message is sent to a real recipient, with an `isnap_live_` key and with an `isnap_test_` key alike. Retry a `429` after `Retry-After` seconds. Retry a `500` or a `503` up to 2 times, with exponential backoff. Do not retry any other `4xx`: fix the request. Retry a write only on an operation that honors `Idempotency-Key`, with the key of the first attempt. Responses carry personal data: handles, names and message text. servers: - url: https://api.isnap.ai security: - bearerAuth: [] paths: /v1/byod/pair: post: summary: Issue a BYOD activation code description: >- Issues a single-use activation code, valid 5 minutes, with the download links of the bridge app. Accepts an API key. A line-scoped key is not limited to its list on this operation: each code it issues can create a line. The user installs the bridge app on their Mac, paired with their iPhone, or on their Android phone, and enters the code. That creates a new BYOD line on your account, with `status: active`, and iSnap sends `line.connected`. The app decides the platform: a Mac gives an iMessage line, an Android phone an Android line. The `phone_number` of the line is empty until the line's device reports it; no event announces it, so read the line. Issuing a code sends no event. An account that is not a wholesale partner needs a free BYOD slot, and no operation that an API key can call buys one. The call returns `402 payment_required` when the account has no BYOD slot, and `404 no_slot_available` when every slot is used by a line that is not terminated. A wholesale partner needs no slot. The slot is checked when the code is issued, not when it is used, and a code reserves no slot. Every call issues another code, and `Idempotency-Key` is ignored. Each pairing creates a new line: no operation moves a BYOD line to another device. End a BYOD line with `POST /v1/lines/{id}/terminate`, which frees its slot. The body accepts `metadata` only: any other key returns `400 validation_failed`. requestBody: content: application/json: schema: $ref: '#/components/schemas/ByodPairBody' responses: '201': description: The activation code and the download links of the bridge app. content: application/json: schema: $ref: '#/components/schemas/ByodPairEnvelope' '400': description: >- Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: No valid credential. `error.code` is `unauthorized`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- No free BYOD slot. `error.code` is `no_slot_available`: every slot the account pays for is used by a BYOD line that is not terminated. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: >- Too many requests. `error.code` is `rate_limit_exceeded` when more than 100 requests came from the same network address in 60 seconds, whatever their API key or account: wait `error.retry_after` seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: >- Unexpected failure. `error.code` is `internal_error`. An operation that takes a JSON body also returns it when the body, sent as `application/json`, is not valid JSON. Quote `trace_id` when you report it to iSnap. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerAuth: [] components: schemas: ByodPairBody: type: object properties: metadata: type: object additionalProperties: nullable: true description: >- Your metadata for the line that this pairing creates. It is copied onto the line, returned on every read of that line, and sent as `data.metadata` on its `line.*` events. At most 20 keys and 8,192 bytes once serialized as JSON. example: crm_contact_id: c_123 additionalProperties: false description: >- Metadata for the line that the pairing creates. The body accepts no other key. ByodPairEnvelope: type: object properties: success: type: boolean enum: - true description: Always `true` on a success response. data: $ref: '#/components/schemas/ByodPairResponse' trace_id: type: string description: >- Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap. request_id: type: string description: >- Id of the request that produced this response: `req_` followed by 25 letters or digits. required: - success - data - trace_id - request_id ErrorEnvelope: type: object properties: success: type: boolean enum: - false description: Always `false` on an error response. data: nullable: true description: Always `null` on an error response. error: type: object properties: status: type: integer description: The HTTP status of the response. code: type: string description: >- Stable machine-readable code that names the refusal. Branch on this value. message: type: string description: >- Text for a person. It can change between versions: do not branch on it. retry_after: type: integer nullable: true description: >- Seconds to wait before the next attempt. Set on the `429` responses that know a delay, where the `Retry-After` header carries the same value. When it is above 60 seconds, do not wait in a request: schedule the call, or report the time. `null` on every other error. retry_at: type: string nullable: true description: >- ISO 8601 timestamp at which the refusal ends. Set only on `429 rebind_cap_reached`. `null` on every other error. issues: type: array nullable: true items: type: object properties: path: type: array items: anyOf: - type: string - type: number description: >- Where the problem is: the field names and array indexes that lead to it. message: type: string description: Text for a person. code: type: string description: >- Kind of problem. On `validation_failed`, for example `invalid_type`, `invalid_value`, `invalid_format`, `invalid_union`, `invalid_key`, `invalid_element`, `too_small`, `too_big`, `not_multiple_of`, `unrecognized_keys` or `custom`. The list is open: read `path` and `message`. min: type: integer description: >- Smallest accepted value. Present only on `limit_out_of_bounds`, `mac_quantity_not_a_pack`, `byop_reduction_strands_mac_sessions` and `byop_reduction_strands_byod_lines`. max: type: integer description: >- Largest accepted value. Present only on `limit_out_of_bounds` and `mac_sessions_exceed_byop_lines`, and on the `too_big` issue of an `Idempotency-Key` header longer than 255 characters. required: - path - message - code description: >- Problems found in the request, one entry each. Set on most `400 validation_failed` responses and on the refusals that name a field: a refused `handle` of `POST /v1/lookup` has `issues: null`. `null` on every other error. required: - status - code - message - retry_after - retry_at - issues description: >- What went wrong. The six fields are always present; `retry_after`, `retry_at` and `issues` are `null` when they do not apply. trace_id: type: string description: >- Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap. request_id: type: string description: >- Id of the request that produced this response: `req_` followed by 25 letters or digits. required: - success - data - error - trace_id - request_id description: The body of an error response. ByodPairResponse: type: object properties: activation_code: type: string description: >- Single-use activation code: `act_` followed by 25 letters or digits. Whoever enters it in the bridge app before `expires_at` creates a line on your account: handle it as a credential. example: act_4Lp8Rn9Fh2Lm5Qx7Vw1Yz4Bc6 expires_at: type: string format: date-time description: >- Timestamp at which the activation code stops working: 5 minutes after it is issued. download_urls: $ref: '#/components/schemas/ByodDownloadUrls' bridge_version: type: string description: >- Version of the bridge app, as set at iSnap. It can differ from the version that `GET /v1/apps` reports. example: 1.0.330 required: - activation_code - expires_at - download_urls - bridge_version description: An activation code and the download links of the bridge app. ByodDownloadUrls: type: object properties: android: type: string format: uri description: >- Stable URL that redirects to the current Android installer of the bridge app. It returns `404` while no Android installer is published: `GET /v1/apps` reports which installers are available. example: https://api.isnap.ai/device/apps/download/android macos: type: string format: uri description: >- Stable URL that redirects to the current macOS installer of the bridge app. It returns `404` while no macOS installer is published: `GET /v1/apps` reports which installers are available. example: https://api.isnap.ai/device/apps/download/macos required: - android - macos description: >- Download links of the bridge app, one per platform. The same links as `GET /v1/apps`. securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key created in the iSnap dashboard, or a trial key, sent as `Authorization: Bearer `. An API key starts with `isnap_live_` or `isnap_test_`; both act on the same account, lines and billing. A trial key acts on its trial only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.