openapi: 3.0.0
info:
  description: APIs for interacting with Cadana Embedded Consumer Wallets
  version: 1.0.0
  title: Embedded Consumer Wallets Balances Contracts API
  termsOfService: https://cadanapay.com/terms-and-conditions
  contact:
    email: api@cadanapay.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
  description: Prod Server
- url: https://dev-api.cadanapay.com
  description: Dev Server
security:
- Authorization: []
tags:
- name: Contracts
  description: APIs for interacting with contracts
paths:
  /v1/contract-templates:
    get:
      summary: List Templates
      description: Fetch all contract tempaltes
      operationId: retrieveContractTemplates
      tags:
      - Contracts
      responses:
        '200':
          $ref: '#/components/responses/GetContractTemplatesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
      - Authorization: []
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
  /v1/contracts:
    get:
      summary: List
      description: Fetch all contracts
      operationId: retrieveContracts
      tags:
      - Contracts
      parameters:
      - name: personId
        in: query
        required: false
        schema:
          type: string
          format: uuid
        example: c30133cc-8d0e-42e5-b18c-24532e46b53e
        description: Optional UUID of the person to filter the contracts
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetContractsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
      - Authorization: []
    post:
      summary: Create
      description: Create a contract
      operationId: createContracts
      tags:
      - Contracts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContractRequest'
      responses:
        '200':
          description: create contract response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/uuid'
                  name:
                    type: string
                    description: Contract name
                  personId:
                    $ref: '#/components/schemas/uuid'
                  signatures:
                    type: array
                    description: List of signatures required for the contract
                    items:
                      type: object
                      properties:
                        emailAddress:
                          type: string
                          format: email
                          description: Signer's email address
                        id:
                          $ref: '#/components/schemas/uuid'
                        lastViewedAt:
                          type: integer
                          format: int64
                          description: Timestamp when the contract was last viewed
                        name:
                          type: string
                          description: Signer's name
                        order:
                          type: integer
                          description: Signing order
                        signedAt:
                          type: integer
                          format: int64
                          description: Timestamp when the contract was signed
                        status:
                          type: string
                          description: Signature status
                          enum:
                          - unsigned
                          - signed
                  status:
                    type: string
                    description: Contract status
                  subject:
                    type: string
                    description: Contract email subject
                  templateId:
                    $ref: '#/components/schemas/uuid'
                  title:
                    type: string
                    description: Contract title
              example:
                id: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                name: Jane Doe - Standard Global Contractor Agreement
                personId: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                signatures:
                - emailAddress: admin@example.com
                  id: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                  lastViewedAt: 0
                  name: Admin
                  order: 0
                  signedAt: 0
                  status: unsigned
                - emailAddress: worker@example.com
                  id: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                  lastViewedAt: 0
                  name: Jane Doe
                  order: 1
                  signedAt: 0
                  status: unsigned
                status: awaiting business signature
                subject: The contract is ready for signature
                templateId: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                title: Acme Corp has sent you a contract for signature
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
      - Authorization: []
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
  /v1/contracts/{contractId}:
    get:
      summary: Retrieve
      description: Retrieve a single contract by ID
      operationId: retrieveContract
      tags:
      - Contracts
      parameters:
      - $ref: '#/components/parameters/contractId'
      - name: includeDownloadUrl
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: When true, includes a presigned download URL for the contract PDF (valid for 15 minutes)
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          description: retrieve contract response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/contract'
                - type: object
                  properties:
                    downloadUrl:
                      type: string
                      description: Presigned S3 download URL for the contract PDF. Only included when includeDownloadUrl=true.
                      example: https://storage.example.com/contracts/d52e4a13-7b6f-4c8d-a9e1-2f3b5c7d8e9a.pdf?token=abc123&expires=900
                    downloadUrlExpiresAt:
                      type: integer
                      description: Epoch timestamp when the download URL expires. Only included when includeDownloadUrl=true.
                      example: 1689760750
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
      - Authorization: []
  /v1/contracts/{contractId}/signingUrl:
    get:
      summary: Signing URL
      description: Get contract signing URL. The generated links last for 336 hours.
      operationId: getContractSigningUrl
      tags:
      - Contracts
      parameters:
      - $ref: '#/components/parameters/contractId'
      - name: redirectUrl
        in: query
        description: URL to redirect to after signing the contract
        required: false
        schema:
          type: string
          format: uri
          example: https://www.google.com
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetContractSigningURLResponse'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - Authorization: []
  /v1/contracts-upload:
    post:
      summary: Upload Contract
      description: Upload a contract PDF using a fileId from the files API
      operationId: uploadContract
      tags:
      - Contracts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadContractRequest'
      responses:
        '200':
          description: upload contract response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/uuid'
                  name:
                    type: string
                    description: Contract name
                  personId:
                    $ref: '#/components/schemas/uuid'
                  status:
                    type: string
                    description: Contract status
              example:
                id: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                name: Employment Agreement
                personId: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                status: completed
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
      - Authorization: []
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
components:
  schemas:
    signer:
      type: object
      properties:
        email:
          type: string
          example: batman@gothammail.com
          format: email
        name:
          type: string
          example: Batman Jr
    contractSignature:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        emailAddress:
          type: string
          example: signer@example.com
        name:
          type: string
          example: John Doe
        order:
          type: integer
          example: 0
        status:
          type: string
          example: signed
        signedAt:
          type: integer
          example: 1689759850
        lastViewedAt:
          type: integer
          example: 1689759850
    UploadContractRequest:
      type: object
      required:
      - personId
      - fileId
      - contractName
      properties:
        personId:
          $ref: '#/components/schemas/uuid'
        fileId:
          $ref: '#/components/schemas/uuid'
        contractName:
          type: string
          description: Name of the contract
          example: Employment Agreement
    uuid:
      type: string
      format: uuid
      example: 8ef9a712-cdae-4110-b1ea-9ba95abbee6e
    NotFoundError:
      description: Not Found
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: resource_not_found
        message: Requested resource could not be found.
    InternalError:
      description: Internal server error
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: internal_error
        message: An unexpected error occurred. Please try again later.
    BadRequestError:
      description: Bad input provided by client
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          params:
            description: A map for meta data around the error that occurred
            type: object
      example:
        code: invalid_request_body
        message: The request body provided is not valid
        params:
          field: Value is invalid.
    contract:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        templateId:
          $ref: '#/components/schemas/uuid'
        status:
          type: string
          example: completed
        personId:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          example: Edward Petersen - Standard Global Contractor Agreement
        signatures:
          type: array
          items:
            $ref: '#/components/schemas/contractSignature'
        createdAt:
          type: integer
          example: 1689759850
        customContractAttached:
          type: boolean
          example: false
    contractTemplate:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        createdTimestamp:
          type: integer
          example: 1702002274
          format: int64
        lastUpdatedTimestamp:
          type: integer
          example: 1702002274
          format: int64
        personType:
          example: employee
          type: string
        type:
          example: regular
          type: string
        country:
          example: US
          type: string
        name:
          example: Standard Employee Agreement
          type: string
        templateString:
          description: The template formatted as an html
          type: string
        templateVariables:
          type: array
          items:
            $ref: '#/components/schemas/templateVariable'
        tenantKey:
          example: abc123
          type: string
    CreateContractRequest:
      type: object
      required:
      - templateId
      - personId
      - sender
      properties:
        templateId:
          $ref: '#/components/schemas/uuid'
        personId:
          $ref: '#/components/schemas/uuid'
        sender:
          $ref: '#/components/schemas/signer'
        suppressNotification:
          type: boolean
          description: Whether to suppress email notifications (optional, defaults to false)
          default: false
    templateVariable:
      type: object
      properties:
        name:
          example: firstName
          type: string
        label:
          example: First Name
          type: string
        ref:
          example: person.firstName
          type: string
        type:
          example: string
          type: string
        description:
          example: This is the employee's first name
          type: string
        isRequired:
          example: true
          type: boolean
    Error:
      type: object
      properties:
        code:
          description: A machine parsable error code
          type: string
          enum:
          - invalid_request_body
          - resource_not_found
          - forbidden
          - internal_error
        message:
          description: A human readable message describing the error
          type: string
  parameters:
    contractId:
      name: contractId
      in: path
      description: The unique identifier for the the contract
      required: true
      schema:
        type: string
        format: uuid
    XMultiTenantKey:
      name: X-MultiTenantKey
      in: header
      required: false
      schema:
        type: string
      description: Required when using a Platform API token. The tenant key identifying which business to operate on.
  responses:
    InternalError:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
    NotFoundError:
      description: Requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    GetContractSigningURLResponse:
      description: get contract signing url response
      content:
        application/json:
          schema:
            type: object
            properties:
              url:
                type: string
                description: Signing URL
                example: https://app.cadanapay.com/sign-contract?token=abc123&redirectUrl=https%3A%2F%2Fwww.google.com
              signer:
                type: string
                description: The type of signer
                enum:
                - person
                - business
                example: business
    GetContractsResponse:
      description: get contracts response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/contract'
    GetContractTemplatesResponse:
      description: get contract templates response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/contractTemplate'
    BadRequestError:
      description: Bad input provided by client
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: API_SECRET_KEY
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true