> ## 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. # Revoke a trial > Ends a trial that your account owns, frees the prospect's handle and disables the trial key. * **Credential:** an API key of the account that owns the trial. A trial key returns `401 unauthorized`. * **Line-scoped keys:** the list of lines of a [line-scoped key](/authentication#line-scoped-keys) is not applied. * **`Idempotency-Key`:** not honored. A repeated revoke is safe: it returns `200` with `already_revoked: true`. See [Revoking a trial](/guides/trials#revoking-a-trial). * **Events:** sends `trial.revoked`. A repeated revoke, and a revoke of a trial that never paired and whose pairing window had already ended, send no event: see [Events](/guides/trials#events). * **Limits:** `reason: rebind` can be turned off or limited per rolling 24 hours: see [Revoking a trial](/guides/trials#revoking-a-trial). ## Errors | Status | `error.code` | When | | - | - | - | | 400 | `validation_failed` | An unknown field, or an unknown `reason`. | | 403 | `rebind_not_allowed` | `reason: rebind`, and rebind is turned off for your account. | | 404 | `trial_not_found` | The id is unknown, or the trial belongs to another account. | | 422 | `admin_reason_forbidden` | `reason: admin` sent with an API key. | | 429 | `rebind_cap_reached` | The limit of `rebind` revokes per rolling 24 hours is reached. `error.retry_after` and the `Retry-After` header give the seconds to wait, and `error.retry_at` the timestamp at which the oldest counted revoke leaves the 24 hours. | The errors that every operation shares are in [Errors](/errors-and-rate-limits#errors). ## OpenAPI ````yaml POST /v1/trial/{trial_id}/revoke 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/trial/{trial_id}/revoke: post: summary: Revoke a trial description: >- Ends a trial of the account, in any status, one that is still pairing included. Accepts an API key. A line-scoped key is not limited to its list on this operation. From then on the trial key returns `401`, the handle of the prospect can pair with a new trial immediately, and an account limited to one trial can start another. The prospect receives no message, and their later messages to the line are dropped. Sends `trial.revoked`. A trial of another account, or an unknown id, returns `404 trial_not_found`. Revoking a trial that is already revoked returns `200` with `already_revoked: true` and sends no event. Revoking a trial whose pairing window already ended stores the reason `pairing_expired`, whatever `reason` you sent, and sends no event. The body is optional, and `reason` defaults to `partner`. `reason: rebind` is limited: it returns `403 rebind_not_allowed` when iSnap disabled it for the account, and `429 rebind_cap_reached` over the limit, with `error.retry_after`, `error.retry_at` and a `Retry-After` header. The limit is 3 per rolling 24 hours for an account that is not a wholesale partner, and a wholesale partner has no limit, unless iSnap set another value for the account. `reason: admin` sent with an API key returns `422 admin_reason_forbidden`. parameters: - schema: type: string minLength: 1 example: trl_4Lp8Rn2xY7wQ9mK3vB5nH8dF2 description: >- Id of the trial, as returned in `trial_id` by `POST /v1/trial/init`: `trl_` followed by 25 letters or digits. required: true description: >- Id of the trial, as returned in `trial_id` by `POST /v1/trial/init`: `trl_` followed by 25 letters or digits. name: trial_id in: path requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/TrialRevokeBody' responses: '200': description: The trial is revoked, by this call or by an earlier one. content: application/json: schema: $ref: '#/components/schemas/TrialRevokeEnvelope' '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' '403': description: >- Refused. `error.code` is `forbidden` when the request carries neither an API key in its `Authorization` header nor the header `X-Requested-With: XMLHttpRequest`. It is `rebind_not_allowed` when `reason` is `rebind` and iSnap disabled rebind for the account. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- Not found. `error.code` is `trial_not_found`: the account has no trial with this id. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: >- The request breaks a rule of this operation. `error.code` is `admin_reason_forbidden`: `reason` is `admin` and the request is made with an API key. 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. It is `rebind_cap_reached` when `reason` is `rebind` and the account reached its limit of rebinds: `error.retry_at` then gives the time at which the oldest rebind counted leaves the 24 hours, and `error.retry_after` the same delay in 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: TrialRevokeBody: type: object properties: reason: type: string enum: - rebind - partner - admin description: >- `partner` (default): you end the trial. `rebind`: you end it so that the same prospect can start a new one; limited per account. `admin`: reserved for dashboard sessions, and refused with an API key (`422 admin_reason_forbidden`). example: rebind additionalProperties: false description: The reason of a revoke. The body is optional. TrialRevokeEnvelope: type: object properties: success: type: boolean enum: - true description: Always `true` on a success response. data: $ref: '#/components/schemas/TrialRevokeData' 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. TrialRevokeData: type: object properties: status: type: string enum: - revoked description: Always `revoked`. already_revoked: type: boolean description: >- `true` when the trial was already revoked before this call. No event is sent in that case. reason: type: string enum: - rebind - partner - admin - pairing_expired description: >- The reason stored on the trial: the one you sent, or `pairing_expired` when the pairing window had already ended. When `already_revoked` is `true`, the reason stored by the first revoke. example: rebind required: - status - already_revoked - reason description: The result of a revoke. 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.