Affinda Webhooks API

openapi: 3.2.0
info:
  title: Affinda Annotations Add x-hidden to endpoints Webhooks API
  version: 3.0.0
  description: Affinda Annotations API — subset of the Affinda v3 Document Processing API.
servers:
- url: https://{region}.affinda.com
  description: 'Select the correct server for your instance: api (AUS/Global), api.us1 (US), or api.eu1 (EU).'
  variables:
    region:
      default: api
      description: The instance region. Use 'api' for AUS/Global, 'api.us1' for US, or 'api.eu1' for EU. You can find your region in the Affinda web app URL.
      enum:
      - api
      - api.eu1
      - api.us1
      x-ms-parameter-location: client
security:
- ApiKeyAuth: []
tags:
- name: Webhooks
  description: 'Manage webhook integrations with your apps.


    Affinda have implemented webhooks to allow the data extracted by Affinda to be ''pushed'' to you when an event occurs

    (e.g. document parsed or document validated), instead of you having to constantly poll our API to ''pull'' the data to your system.

    '
paths:
  /v3/resthook_subscriptions:
    get:
      tags:
      - Webhooks
      summary: Get list of all resthook subscriptions
      operationId: getAllResthookSubscriptions
      description: Returns your resthook subscriptions.
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: All matching resthook subscriptions.
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                - count
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/ResthookSubscription'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
      - Webhooks
      summary: Create a resthook subscription
      operationId: createResthookSubscription
      description: 'After a subscription is successfully created, we''ll send a POST request to your target URL with a `X-Hook-Secret` header. <br />

        You need to response to this request with a 200 status code to confirm your subscribe intention. <br />

        Then, you need to use the `X-Hook-Secret` to activate the subscription using the [/resthook_subscriptions/activate](#post-/v3/resthook_subscriptions/activate) endpoint. <br />

        For more information and detailed instructions, [see our webhooks documentation here.](https://docs.affinda.com/docs/webhooks)'
      responses:
        '201':
          description: Successfully created a resthook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResthookSubscription'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResthookSubscriptionCreate'
  /v3/resthook_subscriptions/{id}:
    get:
      tags:
      - Webhooks
      summary: Get specific resthook subscription
      operationId: getResthookSubscription
      description: Return a specific resthook subscription.
      parameters:
      - in: path
        required: true
        name: id
        description: Resthook subscription's ID
        schema:
          $ref: '#/components/schemas/ResthookSubscription_properties-id'
      responses:
        '200':
          description: Successfully retrieved resthook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResthookSubscription'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
      - Webhooks
      summary: Update a resthook subscription
      operationId: updateResthookSubscription
      description: Update data of a resthook subscription.
      parameters:
      - in: path
        required: true
        name: id
        description: ResthookSubscription's ID
        schema:
          $ref: '#/components/schemas/ResthookSubscription_properties-id'
      requestBody:
        description: ResthookSubscription data to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResthookSubscriptionUpdate'
      responses:
        '200':
          description: Successfully updated resthook subscription data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResthookSubscription'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      tags:
      - Webhooks
      summary: Delete a resthook subscription
      operationId: deleteResthookSubscription
      description: Deletes the specified resthook subscription from the database.
      parameters:
      - in: path
        required: true
        name: id
        description: ResthookSubscription's ID
        schema:
          $ref: '#/components/schemas/ResthookSubscription_properties-id'
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/resthook_subscriptions/activate:
    post:
      tags:
      - Webhooks
      summary: Activate a resthook subscription
      operationId: activateResthookSubscription
      description: 'After creating a subscription, we''ll send a POST request to your target URL with a `X-Hook-Secret` header. <br />

        You should response to this with a 200 status code, and use the value of the `X-Hook-Secret` header that you received to activate the subscription using this endpoint.'
      parameters:
      - in: header
        required: true
        name: X-Hook-Secret
        description: The secret received when creating a subscription.
        schema:
          type: string
          example: 36bacde97882f563992b00a89163eb9058d956fdc2f914870b8903ec93cdf372
      responses:
        '200':
          description: Successfully activated a resthook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResthookSubscription'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  schemas:
    PaletteColorOptions:
      type: object
      required:
      - main
      properties:
        main:
          type: string
        light:
          type: string
        dark:
          type: string
        contrastText:
          type: string
    Organization_properties-identifier:
      type: string
      description: Uniquely identify an organization.
      example: mEFayXdO
    targetUrl:
      type: string
      description: URL of the resthook's receiver.
      example: https://my-site.com/receive
    name:
      type: string
    ResthookSubscriptionCreate:
      type: object
      required:
      - targetUrl
      - event
      properties:
        targetUrl:
          $ref: '#/components/schemas/targetUrl'
        event:
          $ref: '#/components/schemas/ResthookEvent'
        organization:
          type: string
          allOf:
          - $ref: '#/components/schemas/Organization_properties-identifier'
          - type: string
            description: Specify to create an organization scope resthook. Not required if you're a member of only 1 organization.
        workspace:
          type: string
          allOf:
          - $ref: '#/components/schemas/identifier'
          - type: string
            description: Specify to create a workspace scope resthook.
        version:
          $ref: '#/components/schemas/version'
    version:
      type: string
      enum:
      - v1
      - v2
      - v3
      description: Version of the resthook subscription. Determines the resthook body being fired.
      example: v3
    ThemeConfig:
      type: object
      properties:
        palette:
          type: object
          properties:
            mode:
              type: string
              enum:
              - light
              - dark
            background:
              oneOf:
              - type: string
              - type: object
                properties:
                  default:
                    type: string
                  paper:
                    type: string
            text:
              type: object
              properties:
                primary:
                  type: string
                secondary:
                  type: string
                disabled:
                  type: string
            divider:
              type: string
            primary:
              $ref: '#/components/schemas/PaletteColorOptions'
            secondary:
              $ref: '#/components/schemas/PaletteColorOptions'
            success:
              $ref: '#/components/schemas/PaletteColorOptions'
            annotation:
              $ref: '#/components/schemas/PaletteColorOptions'
            error:
              $ref: '#/components/schemas/PaletteColorOptions'
            info:
              $ref: '#/components/schemas/PaletteColorOptions'
            warning:
              $ref: '#/components/schemas/PaletteColorOptions'
        typography:
          type: object
          properties:
            fontFamily:
              type: string
            fontSize:
              oneOf:
              - type: string
              - type: number
            fontWeightRegular:
              type: string
            fontWeightMedium:
              type: string
            fontWeightBold:
              type: string
        borderRadius:
          type: number
        fontUrl:
          type: string
    OrganizationRole:
      type: string
      enum:
      - admin
      - member
      example: admin
    PaginatedResponse:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          example: 10
          description: Number of items in results.
          minimum: 0
        next:
          type:
          - string
          - 'null'
          description: URL to request next page of results.
        previous:
          type:
          - string
          - 'null'
          description: URL to request previous page of results.
    identifier:
      type: string
      description: Uniquely identify a workspace.
      example: mEFayXdO
    ResthookEvent:
      type: string
      enum:
      - resume.parse.succeeded
      - resume.parse.failed
      - resume.parse.completed
      - invoice.parse.succeeded
      - invoice.parse.failed
      - invoice.parse.completed
      - invoice.validate.completed
      - document.parse.succeeded
      - document.parse.failed
      - document.parse.completed
      - document.validate.completed
      - document.classify.succeeded
      - document.classify.failed
      - document.classify.completed
      - document.rejected
      - annotation.validated
      description: The event name to subscribe to.
      example: document.parse.succeeded
    ResthookSubscription_properties-id:
      type: integer
      description: Resthook subscription's ID.
    ResthookSubscriptionWorkspace:
      type: object
      required:
      - identifier
      - name
      - organization
      properties:
        identifier:
          $ref: '#/components/schemas/identifier'
        name:
          $ref: '#/components/schemas/name'
        organization:
          $ref: '#/components/schemas/Organization'
    ResthookSubscriptionUpdate:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/ResthookEvent'
        organization:
          $ref: '#/components/schemas/Organization_properties-identifier'
        workspace:
          $ref: '#/components/schemas/identifier'
        version:
          $ref: '#/components/schemas/version'
    ResthookSubscription:
      type: object
      required:
      - id
      - event
      - organization
      - workspace
      - targetUrl
      - active
      - autoDeactivated
      - autoDeactivateReason
      - version
      properties:
        id:
          type: integer
          description: Resthook subscription's ID.
        event:
          $ref: '#/components/schemas/ResthookEvent'
        organization:
          $ref: '#/components/schemas/Organization'
        workspace:
          $ref: '#/components/schemas/ResthookSubscriptionWorkspace'
        targetUrl:
          type: string
          description: URL of the resthook's receiver.
          example: https://my-site.com/receive
        active:
          type: boolean
          description: Resthooks only fire for active subscriptions.
          example: true
        autoDeactivated:
          type: boolean
          description: Resthook subscriptions can be auto deactivated if the receiver continuously returns error status code over a period of time.
          example: true
        autoDeactivateReason:
          type: string
          description: The reason for the subscription being auto deactivated. May contains the error response that the receiver returned.
          example: 'Resthook fails after 10 retries. The last error received was: 500 - Internal server error.'
        version:
          type: string
          enum:
          - v1
          - v2
          - v3
          description: Version of the resthook subscription. Determines the resthook body being fired.
          example: v3
    RequestError:
      type: object
      additionalProperties: false
      required:
      - type
      - errors
      properties:
        type:
          type: string
          example: validation_error
        errors:
          type: array
          items:
            type: object
            required:
            - attr
            - code
            - detail
            properties:
              attr:
                type:
                - string
                - 'null'
                example: non_field_errors
              code:
                type: string
                example: unique
              detail:
                type: string
                example: This index name has already been used
    Organization:
      type: object
      properties:
        identifier:
          type: string
          description: Uniquely identify an organization.
          example: mEFayXdO
        name:
          type: string
          example: Grove Street King
        userRole:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OrganizationRole'
          description: The role of the logged in user within the organization.
        avatar:
          type:
          - string
          - 'null'
          description: URL of the organization's avatar.
          example: https://affinda-api.s3.amazonaws.com/media/org-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
        resthookSignatureKey:
          type:
          - string
          - 'null'
          description: Used to sign webhook payloads so you can verify their integrity.
          example: 465c6598bd34c0558f0ce256c43209d49fa85b0ff3e4c18b24e408b7563143ad
        isTrial:
          type: boolean
        validationToolConfig:
          type:
          - object
          - 'null'
          description: Configuration of the embeddable validation tool.
          properties:
            theme:
              $ref: '#/components/schemas/ThemeConfig'
            hideActions:
              type: boolean
              description: Hide the confirm document button and other actions.
            hideCollection:
              type: boolean
              description: Hide the collection selector.
            hideEditPages:
              type: boolean
              description: Hide the edit pages button.
            hideExport:
              type: boolean
              description: Hide the export menu.
            hideFilename:
              type: boolean
              description: Hide the filename input.
            hideShowRawValues:
              type: boolean
              description: Hide the toggle for showing raw annotation values.
            hideReject:
              type: boolean
              description: Hide the reject document button.
            hideReparse:
              type: boolean
              description: Hide the reparse button.
            hideRunOcr:
              type: boolean
              description: Hide the run OCR button.
            hideTags:
              type: boolean
              description: Hide the tags editor.
            hideWarnings:
              type: boolean
              description: Hide the warnings panel.
            restrictDocumentSplitting:
              type: boolean
              description: Disable the page editor after a document has been split once.
            disableCurrencyFormatting:
              type: boolean
              description: Disable currency formatting of decimals values.
            disableEditDocumentMetadata:
              type: boolean
              description: Disable editing document metadata. Makes the collection selector, filename input and tags editor read only.
            disableManualAnnotationEditing:
              type: boolean
              description: Disable manual editing of annotation values via the validation popover.
            hideDocumentStatus:
              type: boolean
              description: Hide the document status indicator in the toolbar.
        showCustomFieldCreation:
          type: boolean
          description: Whether to show the custom field creation in the UI.
  parameters:
    limitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        example: 20
      description: The numbers of results to return.
      x-ms-parameter-location: method
    offsetParam:
      in: query
      name: offset
      required: false
      schema:
        type: integer
        minimum: 0
        example: 0
      description: The number of documents to skip before starting to collect the result set.
      x-ms-parameter-location: method
  responses:
    400Error:
      description: Bad request. If it is a validation error will contain a list of each invalid field
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
    204NoContent:
      description: Delete successful, no content returned
    DefaultError:
      description: UnexpectedError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
    401Error:
      description: Authorisation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Basic authentication using an API key, e.g. `{Authorization: Bearer aff_0bb4fbdf97b7e4111ff6c0015471094155f91}`.

        You can find your API key within the Settings page of the [Affinda web app](https://app.affinda.com/). You can obtain an API key by [signing up for a free trial](https://app.affinda.com/auth/register).'