{
  "openapi": "3.1.0",
  "info": {
    "title": "SignatureAPI: Senders",
    "summary": "SignatureAPI is an API-first electronic signature platform.",
    "version": "1.18.0",
    "description": "SignatureAPI is a REST API for sending documents for electronic signature. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs and status codes.\n\n### Key concepts\n\nAn **envelope** is the central object. It holds documents and recipients, and manages the signing process from start to finish.\n\nA **document** is a PDF or DOCX file within an envelope. Documents contain **places** — interactive fields like signatures, initials, text inputs, checkboxes, and dropdowns positioned at specific locations.\n\nA **recipient** is a person who receives an envelope. There are three types:\n- **Signer** — signs documents\n- **Approver** — reviews and approves without signing\n- **Preparer** — fills in fields before the signer receives the documents\n\nA **ceremony** is the interactive session where a recipient authenticates and performs their actions. SignatureAPI supports three authentication methods: email link, email code, and custom.\n\nA **deliverable** is the final output — a signed PDF with an audit trail, generated after all recipients complete their actions.\n\nA **sender** is a verified email address that SignatureAPI sends signing requests on behalf of.\n\nAn **upload** is a file stored in SignatureAPI for use as a document source in envelopes.\n\n### HTTP Semantics\n\nWe use HTTP verbs GET, POST, DELETE as defined in RFC 9110, and PATCH as defined in RFC 5789.\n\nWe use the following HTTP Status codes for successful responses:\n\n- **200 OK**: Request succeeded for a GET, POST, or PATCH call.\n- **201 Created**: Request succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource.\n\n### Versioning\n\nWe use [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html):\n\n- We increment Major (the X in X.Y.Z) versions when we make a change that breaks backward compatibility. The current major version is 1.\n- We increment Minor (the Y in X.Y.Z) versions when we add backward compatible features.\n- We increment Patch (the Z in X.Y.Z) versions when we make backward compatible bug fixes or improvements in the documentation.\n\nSignatureAPI considers the following changes to break backward compatibility:\n\n- Removing or renaming fields, arguments, or enum values.\n- Removing endpoints.\n- Changing the type of fields in the response (for example, from string to integer).\n- Adding a new **required** request parameter.\n\nThese are not breaking changes:\n\n- Any additive change, such as adding endpoints, optional arguments, fields, or enum values.\n- Making a required request parameter optional.\n- Making a validation less restrictive.\n- Changes to error responses. _We do not recommend parsing error responses to perform business logic._\n- Changes to the order of fields returned in a response.\n- Changes to the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.\n- Adding new event types.\n- Changes in the structure and descriptions in this OpenAPI spec.",
    "contact": {
      "name": "Signature API, Inc.",
      "email": "support@signatureapi.com"
    },
    "termsOfService": "https://signatureapi.com/terms"
  },
  "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.\n\nOnce 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.\n",
        "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"
          }
        }
      }
    },
    "/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.\n",
        "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.\n",
        "responses": {
          "204": {
            "description": "The sender was deleted successfully."
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    }
  },
  "components": {
    "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.\n\nYour 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.\n"
      }
    },
    "schemas": {
      "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.\n",
        "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"
        ]
      },
      "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.\n",
        "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.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"
      },
      "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.\n\nWhen 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`.\n\nOnly senders with `verified` status can be used as the sender on an envelope.\n",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "email": {
            "$ref": "#/components/schemas/Sender.Email"
          }
        },
        "required": [
          "email"
        ]
      },
      "Sender.Status": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Sender Status",
        "description": "The current verification status of the sender.\n\n- `pending_verification` — A verification email has been sent but the sender has not yet confirmed.\n- `verified` — The sender confirmed the verification email and can be used to send envelopes.\n- `failed` — The verification email bounced or encountered an error. This sender cannot be used.\n",
        "type": "string",
        "enum": [
          "pending_verification",
          "verified",
          "failed"
        ],
        "examples": [
          "verified"
        ]
      },
      "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.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.\n\nWhen 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`.\n\nOnly senders with `verified` status can be used as the sender on an envelope.\n",
        "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"
        ]
      }
    },
    "parameters": {
      "SenderId": {
        "name": "senderId",
        "in": "path",
        "description": "The unique identifier of a sender.",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Sender.Id"
        }
      }
    },
    "responses": {
      "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.\n\nThis error covers HTTP status codes in the 400 to 499 range. The most common are:\n\n- 400 Bad Request (`bad-request`: the request body is not valid JSON)\n- 401 Unauthorized\n- 402 Payment Required (`live-mode-paused`: live API access is paused because an invoice is unpaid; test keys keep working)\n- 403 Forbidden\n- 409 Conflict\n- 410 Gone\n- 404 Not Found\n- 413 Request Too Large (`request-too-large`: a JSON request body exceeds 1500 KiB, a form-encoded body exceeds 100 KiB, or a form-encoded body has too many parameters)\n- 415 Unsupported Media Type (`unsupported-media-type`: the request body's charset or content encoding is not supported)\n- 422 Unprocessable Content.\n",
        "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."
            }
          }
        }
      },
      "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.\n",
        "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.\n"
            }
          }
        }
      },
      "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.\n",
        "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"
              ]
            }
          }
        }
      }
    },
    "headers": {
      "Location": {
        "required": true,
        "description": "The URL of the created resource",
        "schema": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}
