Receeve Event API

openapi: 3.0.3
info:
  title: InDebted Receive API Documentation Account Event API
  description: 'This is the API definition for interacting with InDebted''s Receive debt servicing platform. For more details please visit the [Integration Documentation](https://docs.indebted.co/docs/receive/receive-knowledge-base).


    **Using this spec in code generators, Postman, or other tooling?** Fetch the raw document at [https://receive-api.indebted.co/openapi/apiSchema.yaml](https://receive-api.indebted.co/openapi/apiSchema.yaml) — that is the canonical OpenAPI file. Prefer it over the in-page download button, which re-serialises the document and can alter value types (e.g. date-formatted strings).'
  contact:
    email: techteam@indebted.co
  version: 1.53.1
servers:
- url: /
  description: API base path
tags:
- name: Event
  description: Event that happened in Receive systems, for example, claim created or email delivered.
paths:
  /v1/{clientId}/get_events:
    get:
      tags:
      - Event
      summary: Get events by event type and timeframe. Paginated.
      operationId: getEvents
      parameters:
      - $ref: '#/components/parameters/ClientIdParameter'
      - $ref: '#/components/parameters/AuthorizationParameter'
      - name: eventType
        in: query
        schema:
          type: string
          pattern: ^(event.claim.created|event.claimDebtPayment.processing|event.debtorEmail.queued|event.debtorSMS.queued|event.promiseToPay.created|event.promiseToPay.invalidated|event.promiseToPay.resolved|event.promiseToPay.expired|event.instalmentsPlan.created|event.instalmentsPlan.failed|event.instalmentsPlan.invalidated|event.instalmentsPlan.resolved|event.instalment.expired|event.instalment.invalidated|event.instalment.resolved|event.instalment.started|event.debtorEmail.delivered)$
        required: true
        description: type of event that happened in Receive system
        example: event.claim.created
      - name: date
        in: query
        schema:
          type: string
          format: date
        required: true
        description: date which to get the events for
        example: '2019-05-28'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 10000
        description: amount of events per page, default is 1000
        example: 1000
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
        description: number of page to retrieve the events for, default is 1
        example: 1
      responses:
        '200':
          $ref: '#/components/responses/200SuccessGetEvents'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429LimitsReached'
        '500':
          $ref: '#/components/responses/500InternalError'
      security:
      - api_key: []
components:
  schemas:
    ClaimDebtPaymentProcessingEvent:
      type: object
      required:
      - messageId
      - timestamp
      - details
      properties:
        messageId:
          type: string
          description: message identifier in Receive system
          example: 51a35d12-9145-4c97-8285-08156681e47
        timestamp:
          type: string
          description: UTC timestamp
          example: '2020-04-17T08:14:29.863Z'
        details:
          type: object
          required:
          - messageType
          - claimRef
          - receeveClaimRef
          - providerName
          - amount
          - currency
          - trackingId
          properties:
            messageType:
              type: string
              description: type of event that happened in Receive system
              example: event.claimDebtPayment.processing.v1
            claimRef:
              type: string
              description: reference to the Claim in external(your) system
              example: ABCDEF123
            receeveClaimRef:
              type: string
              description: reference to the Claim in Receive system
              example: ABCDEF123-2020-01-15
            providerName:
              type: string
              description: Name of payment provider
              example: Trustly
            amount:
              type: integer
              description: Amount of the payment transaction in cents
              example: 2000
            currency:
              $ref: '#/components/schemas/Currency'
            trackingId:
              type: string
              description: Tracking id from payment provider
              example: TRACKINGID123
            paymentReference:
              $ref: '#/components/schemas/PaymentReference'
    ClaimCreatedEvent:
      type: object
      required:
      - messageId
      - timestamp
      - details
      properties:
        messageId:
          type: string
          minLength: 1
          example: 51a35d12-9145-4c97-8285-08156681e47
          description: message identifier in Receive system
        timestamp:
          type: string
          minLength: 1
          description: UTC timestamp
          example: '2020-04-17T08:14:29.863Z'
        details:
          type: object
          required:
          - messageType
          - claimRef
          - receeveClaimRef
          - amount
          - currency
          - dueDate
          properties:
            messageType:
              type: string
              minLength: 1
              example: event.claim.created.v1
              description: type of event that happened in Receive system
            claimRef:
              type: string
              minLength: 1
              example: ABCDEF123
              description: reference to the Claim in external(your) system
            receeveClaimRef:
              type: string
              minLength: 1
              example: ABCDEF123-2020-01-15
              description: reference to the Claim in Receive system
            amount:
              type: integer
              description: Amount of the claim without fees in cents
              example: 2000
            currency:
              $ref: '#/components/schemas/Currency'
            dueDate:
              $ref: '#/components/schemas/DueDate'
    Currency:
      type: string
      example: EUR
      pattern: ^[A-Z]{3}$
      description: 3-digit currency code (ISO 4217)
    PaymentReference:
      type: string
      minLength: 1
      example: paymentReference1
      description: 'Payment reference used in online transactions.

        It is a text reference that can be used to map the money transactions to other external systems.

        '
    DueDate:
      type: string
      format: date
      example: '2019-06-28'
      description: Current due date in your system. Use originalDueDate unless you purchased the debt and need this distinction.
  parameters:
    ClientIdParameter:
      name: clientId
      in: path
      required: true
      description: 'A Receive system identifier that will be assigned automatically.

        It will be used for situations like Support related interventions or data segmentation.

        '
      example: ec702157-705b-42a0-b70e-a60a63dd24ab
      schema:
        type: string
        format: uuid
    AuthorizationParameter:
      in: header
      name: Authorization
      required: true
      description: 'OAuth2 Token (obtained from /oauth2/token )

        Reference: https://docs.indebted.co/docs/receive/integration/use-cases/authentication-use-case

        '
      example: Bearer <access_token>
      schema:
        type: string
  responses:
    200SuccessGetEvents:
      description: Request for get_events is successful
      content:
        application/json:
          schema:
            type: object
            required:
            - events
            - limit
            - page
            - numberOfPages
            properties:
              events:
                type: array
                items:
                  anyOf:
                  - $ref: '#/components/schemas/ClaimCreatedEvent'
                  - $ref: '#/components/schemas/ClaimDebtPaymentProcessingEvent'
              limit:
                type: integer
                description: amount of events per current page
                example: 1000
              page:
                type: integer
                description: current page number
                example: 1
              numberOfPages:
                type: integer
                description: amount of pages with limit that is given for that request
                example: 2
          example:
            page: 1
            limit: 1000
            numberOfPages: 1
            events:
            - messageId: a7d67994-14ad-4371-b810-483fa28318dd
              timestamp: '2024-05-02T08:10:53.504Z'
              details:
                messageType: event.claim.created.v1
                accountReference: ACC-DE-5567
                claimRef: INV-2024-0042
                receeveClaimRef: INV-2024-0042
                amount: 149900
                currency: EUR
                dueDate: '2024-05-01'
    403Forbidden:
      description: Access is denied
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Forbidden
    400BadRequest:
      description: Incorrectly formed request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'Missing required request parameters: [Authorization]'
    429LimitsReached:
      description: Request was throttled
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Too Many Requests
    500InternalError:
      description: Internal error occured
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal error
    401Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header