openapi: 3.2.0
info:
  title: Saperly Consent API
  version: 0.1.0
  description: 'Operations tagged consent across 2 of this provider''s published API definitions: api-saperly-com-openapi.json, saperly-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /
  description: This worker
- url: https://api.saperly.com
  description: Production
security: []
tags:
- name: consent
  description: Track opt-in consent for contacts on your numbers. Record, revoke, list, and check the consent that backs your outbound messaging compliance. (Inbound STOP/START opt-out is handled automatically by the carrier-side keyword path.)
paths:
  /consent:
    get:
      tags:
      - consent
      operationId: consent.list
      parameters: []
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    numberId:
                      type: string
                    peerNumber:
                      type: string
                    consentType:
                      type: string
                      enum:
                      - implied_inbound
                      - explicit_outbound
                    source:
                      type: string
                    grantedAt:
                      type: string
                    revokedAt:
                      anyOf:
                      - type: string
                      - type: 'null'
                  required:
                  - id
                  - numberId
                  - peerNumber
                  - consentType
                  - source
                  - grantedAt
                  - revokedAt
                  additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: AuthorizationDenied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationDenied'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimited'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      summary: List all consent records in the workspace
    post:
      tags:
      - consent
      operationId: consent.record
      parameters: []
      security: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  numberId:
                    type: string
                  peerNumber:
                    type: string
                  consentType:
                    type: string
                    enum:
                    - implied_inbound
                    - explicit_outbound
                  source:
                    type: string
                  grantedAt:
                    type: string
                  revokedAt:
                    anyOf:
                    - type: string
                    - type: 'null'
                required:
                - id
                - numberId
                - peerNumber
                - consentType
                - source
                - grantedAt
                - revokedAt
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: AuthorizationDenied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationDenied'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimited'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      summary: Record consent for a contact
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                numberId:
                  type: string
                  description: The id of your number the consent is scoped to.
                peerNumber:
                  type: string
                  description: The contact phone number, in E.164 format (e.g. `+14155550123`), that the consent applies to.
                consentType:
                  type: string
                  enum:
                  - implied_inbound
                  - explicit_outbound
                  description: 'How consent was obtained: `implied_inbound` (the contact messaged you first) or `explicit_outbound` (the contact explicitly agreed to be contacted).'
                source:
                  type: string
                  description: A free-text note recording where or how consent was captured, kept for your audit trail (e.g. "web signup form").
              required:
              - numberId
              - peerNumber
              - consentType
              - source
              additionalProperties: false
              description: Record proof of consent for a contact on one of your numbers.
        required: true
    servers:
    - url: /
      description: This worker
  /consent/revoke:
    post:
      tags:
      - consent
      operationId: consent.revoke
      parameters: []
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - revoked
                required:
                - status
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: AuthorizationDenied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationDenied'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimited'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      summary: Revoke consent for a contact
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                numberId:
                  type: string
                  description: The id of your number the consent to revoke is scoped to.
                peerNumber:
                  type: string
                  description: The contact phone number, in E.164 format (e.g. `+14155550123`), whose consent should be revoked.
              required:
              - numberId
              - peerNumber
              additionalProperties: false
              description: Revoke a previously recorded consent for a contact on one of your numbers.
        required: true
    servers:
    - url: /
      description: This worker
  /consent/check:
    get:
      tags:
      - consent
      operationId: consent.check
      parameters:
      - name: numberId
        in: query
        schema:
          type: string
          description: The id of your number to check consent against.
        required: true
      - name: peerNumber
        in: query
        schema:
          type: string
          description: The contact phone number, in E.164 format (e.g. `+14155550123`), to check for active consent.
        required: true
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasConsent:
                    type: boolean
                  type:
                    anyOf:
                    - type: string
                      enum:
                      - implied_inbound
                      - explicit_outbound
                    - type: 'null'
                required:
                - hasConsent
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: AuthorizationDenied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationDenied'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimited'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      summary: Check whether a contact has active consent
    servers:
    - url: /
      description: This worker
components:
  schemas:
    AuthorizationDenied:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - AuthorizationDenied
        reason:
          type: string
      required:
      - _tag
      - reason
      additionalProperties: false
    RateLimited:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - RateLimited
        bucket:
          type: string
          description: The rate-limit bucket that was exhausted.
      required:
      - _tag
      - bucket
      additionalProperties: false
    Unauthorized:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - Unauthorized
        message:
          type: string
          description: Why the request was rejected (missing, invalid, or insufficient credentials).
      required:
      - _tag
      - message
      additionalProperties: false
    InternalError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - InternalError
        traceId:
          type: string
          description: A correlation id for this failure — quote it when reporting the problem so the request can be traced.
      required:
      - _tag
      - traceId
      additionalProperties: false
x-refined-from:
- api-saperly-com-openapi.json
- saperly-openapi.yml