signatureapi-com Senders API

openapi: 3.2.0
info:
  title: Signatureapi Com Senders API
  version: 1.18.0
  contact:
    name: Signature API, Inc.
    email: support@signatureapi.com
  termsOfService: https://signatureapi.com/terms
  description: 'Operations tagged Senders across 2 of this provider''s published API definitions: spec_openapi.yaml, signatureapi-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: SignatureAPI Global Server.
  url: https://api.signatureapi.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Senders
paths:
  /senders:
    post:
      operationId: CreateSender
      summary: Create a sender
      x-audience: public
      tags:
      - Senders
      description: 'Registers a new sender email address and starts the verification process. SignatureAPI sends a verification email to the provided address. The sender is returned with `pending_verification` status.


        Once the email owner clicks the confirmation link, the sender status changes to `verified` and can be used on envelopes. SignatureAPI sends signing requests to recipients on behalf of verified senders. Listen for the `sender.verified` or `sender.failed` webhook events to track the outcome.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sender.SenderInput'
      responses:
        '201':
          description: A sender was created successfully.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sender.Sender'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    servers:
    - description: SignatureAPI Global Server.
      url: https://api.signatureapi.com/v1
  /senders/{senderId}:
    parameters:
    - $ref: '#/components/parameters/SenderId'
    get:
      operationId: GetSender
      summary: Retrieve a Sender
      x-audience: public
      tags:
      - Senders
      description: Retrieves the details of a sender. Use this endpoint to check the current verification status of a sender after creation.
      responses:
        '200':
          description: The sender was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sender.Sender'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    delete:
      operationId: DeleteSender
      summary: Delete a sender
      x-audience: public
      tags:
      - Senders
      description: Deletes a sender. Once deleted, this email address can no longer be used on new envelopes. Envelopes already sent with this sender are not affected.
      responses:
        '204':
          description: The sender was deleted successfully.
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    servers:
    - description: SignatureAPI Global Server.
      url: https://api.signatureapi.com/v1
components:
  schemas:
    Sender.Sender:
      x-schema-role: model
      x-schema-direction: output
      title: Sender
      description: 'A **sender** is a verified email address that SignatureAPI sends signing requests on behalf of. Each sender must complete email verification before it can be used with envelopes.


        When you create a sender, SignatureAPI sends a verification email to the provided address. The sender starts in `pending_verification` status. Once the email owner clicks the confirmation link, the status changes to `verified`. If the verification email bounces or encounters an error, the status changes to `failed`.


        Only senders with `verified` status can be used as the sender on an envelope.

        '
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Sender.Id'
        email:
          $ref: '#/components/schemas/Sender.Email'
        status:
          $ref: '#/components/schemas/Sender.Status'
        created_at:
          $ref: '#/components/schemas/Sender.CreatedAt'
      required:
      - id
      - email
      - status
      - created_at
    Sender.CreatedAt:
      x-schema-role: property
      x-schema-direction: output
      type: string
      format: date-time
      title: Sender Created At
      description: Time at which the sender was created. Formatted as an ISO 8601 timestamp.
      examples:
      - '2025-01-01T00:00:00.000Z'
    Sender.Email:
      x-schema-role: property
      x-schema-direction: any
      title: Sender Email
      description: The email address of the sender. SignatureAPI sends signing request emails to recipients on behalf of this address.
      type: string
      format: email
      maxLength: 320
      example: john@example.com
    Shared.ValidationProblem:
      x-schema-role: property
      x-schema-direction: output
      description: 'A validation error response following the RFC 9457 Problem Details format. The API returns this object with HTTP status 422 when a request body fails validation. The `errors` array lists each field-level problem so you can fix them all in one pass.

        '
      properties:
        type:
          type: string
          description: A URL pointing to the validation error documentation. Always `https://signatureapi.com/docs/v1/errors/validation-error`.
          format: uri
          const: https://signatureapi.com/docs/v1/errors/validation-error
          example: https://signatureapi.com/docs/v1/errors/validation-error
        title:
          type: string
          description: A short summary of the problem type. Always `Validation Error`.
          const: Validation Error
          example: Validation Error
        status:
          type: integer
          description: The HTTP status code. Always `422` for validation errors.
          const: 422
          example: 422
        errors:
          type: array
          description: A list of human-readable messages describing each validation failure.
          items:
            type: string
          example:
          - documents[0].url protocol must be HTTPS
          - recipients[0].email must be a valid email address
      required:
      - type
      - title
      - status
      - errors
    Sender.Id:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Sender ID
      description: The unique identifier of the sender.
      examples:
      - a1b2c3d4-e5f6-7890-abcd-ef1234567890
    Sender.Status:
      x-schema-role: property
      x-schema-direction: output
      title: Sender Status
      description: 'The current verification status of the sender.


        - `pending_verification` — A verification email has been sent but the sender has not yet confirmed.

        - `verified` — The sender confirmed the verification email and can be used to send envelopes.

        - `failed` — The verification email bounced or encountered an error. This sender cannot be used.

        '
      type: string
      enum:
      - pending_verification
      - verified
      - failed
      examples:
      - verified
    Sender.SenderInput:
      x-schema-role: model
      x-schema-direction: input
      title: Sender Input
      description: 'A **sender** is a verified email address that SignatureAPI sends signing requests on behalf of. Each sender must complete email verification before it can be used with envelopes.


        When you create a sender, SignatureAPI sends a verification email to the provided address. The sender starts in `pending_verification` status. Once the email owner clicks the confirmation link, the status changes to `verified`. If the verification email bounces or encounters an error, the status changes to `failed`.


        Only senders with `verified` status can be used as the sender on an envelope.

        '
      type: object
      additionalProperties: false
      properties:
        email:
          $ref: '#/components/schemas/Sender.Email'
      required:
      - email
    Shared.Problem:
      x-schema-role: property
      x-schema-direction: output
      type: object
      description: 'An error response following the RFC 9457 Problem Details format. The API returns this object with a `application/problem+json` content type when a request fails. Use the `type` URL to identify the error programmatically and the `detail` field to understand what went wrong.

        '
      additionalProperties: false
      properties:
        type:
          type: string
          description: A URL that identifies the problem type. Points to documentation explaining the error.
          format: uri
          example: https://signatureapi.com/docs/v1/errors/invalid-api-key
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid API Key
        status:
          type: integer
          description: The HTTP status code for this error. Matches the status code in the HTTP response.
          minimum: 100
          maximum: 599
          example: 401
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: Please provide a valid API key in the X-API-Key header.
      required:
      - type
      - title
      - status
      - detail
  parameters:
    SenderId:
      name: senderId
      in: path
      description: The unique identifier of a sender.
      required: true
      schema:
        $ref: '#/components/schemas/Sender.Id'
  responses:
    Shared.ValidationError:
      description: 'The request cannot be processed due to validation errors. This typically involves issues like missing required fields, invalid data formats, or value constraints not being met.

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Shared.ValidationProblem'
          example:
            type: https://signatureapi.com/docs/v1/errors/validation-error
            title: Validation Error
            status: 422
            errors:
            - The title is required
            - The sender.email is not a valid email address
            - The value of recipients[0].key is too long
    Shared.ServerError:
      description: 'The request cannot be processed due to an issue on the server''s side. The client can retry the request in a few minutes, or contact support if the error persists.

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Shared.Problem'
          example:
            type: https://signatureapi.com/docs/v1/errors/server-error
            title: Internal Server Error
            status: 500
            detail: 'There was a problem in our server and your request was not fulfilled. Try again later. If the error persists, please contact support.

              '
    Shared.ClientError:
      description: 'The request cannot be processed due to an issue on the client''s side. This may include invalid request format, insufficient permissions, or requesting non-existent resources. The client should review and correct the request.


        This error covers HTTP status codes in the 400 to 499 range. The most common are:


        - 401 Unauthorized

        - 402 Payment Required (`live-mode-paused`: live API access is paused because an invoice is unpaid; test keys keep working)

        - 403 Forbidden

        - 409 Conflict

        - 410 Gone

        - 404 Not Found

        - 422 Unprocessable Content.

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Shared.Problem'
          example:
            type: https://signatureapi.com/docs/v1/errors/api-key-required
            title: The API Key is required
            status: 401
            detail: A valid API key is required in the X-API-Key header of all requests.
  headers:
    Location:
      required: true
      description: The URL of the created resource
      schema:
        type: string
        format: uri
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Authentication to the API is performed via an API key in the `X-API-Key` header.


        Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

        '
x-refined-from:
- spec_openapi.yaml
- signatureapi-com-openapi.yml