> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.debbiecollect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create interaction

> Create an interaction on a case. Use this to register an incoming message from a debtor or another party, for example a submitted contact form.



## OpenAPI

````yaml POST /v1/{tenantId}/interactions
openapi: 3.1.0
info:
  title: Debbie API Docs
  description: >
    The Debbie API is a RESTful interface, allowing you to programmatically

    update, add and access your data in the platform. It provides predictable
    URLs

    for accessing resources, and uses built-in HTTP features to receive commands
    and

    return responses. This makes it easy to communicate with third party
    systems.


    ## Idempotency


    The Debbie API supports idempotency for non-idempotent requests through the
    optional `Idempotency-Key` header. 

    This ensures that retrying the same request multiple times will produce the
    same result, preventing duplicate operations.


    ### Using Idempotency Keys


    - Include an `Idempotency-Key` header with a unique string (we recommend
    UUIDs)  

    - Maximum key length is 64 characters

    - Keys are valid for 48 hours

    - Responses served from the idempotency cache include an
    `Idempotency-Cached` header


    ### Example

    ```http

    Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

    ```


    ### Error Cases

    - Invalid key format: 400 Bad Request

    - Reusing a key for a different request: 400 Bad Request


    ### Best Practices

    - Use a new key for each unique business transaction

    - Use the same key when retrying a failed request 

    - Store keys with request details for debugging
  contact:
    email: api-support@debbie.dk
  version: v0.1.0
servers:
  - url: https://api.debbiecollect.com
security:
  - bearerAuth: []
tags:
  - name: Authorization
    description: Endpoints for interacting with authorization
  - name: Cases
    description: Endpoints for interacting with cases
  - name: Customers
    description: Endpoints for interacting with customers
  - name: Creditors
    description: Endpoints for interacting with creditors
  - name: Ultimate creditors
    description: >-
      Endpoints for interacting with ultimate creditors. An ultimate creditor is
      the original creditor behind the creditor on a case — for example when a
      debt collection agency forwards cases on behalf of its own client. On
      cases with an ultimate creditor, the creditor template mentions (name,
      address and company identifier) use the details of the ultimate creditor.
  - name: Updates
    description: Endpoints for interacting with updates
  - name: Users
    description: Endpoints for interacting with updates
  - name: Files
    description: Endpoints for interacting with files
  - name: Case vouchers
    description: Endpoints for interacting with case vouchers
  - name: Voucher types
    description: The voucher types of the tenant, used to categorize case vouchers
  - name: Interactions
    description: >-
      Interactions are messages and notes on a case, for example an incoming
      message from a debtor.
  - name: Billing
    description: Endpoints for interacting with billing
  - name: Links
    description: Endpoints for generating links
  - name: Webhooks
    description: >-
      Debbie provides a range of webhooks. To try them out please visit Debbie
      Caseworker and navigate to Settings --> Developers --> Webhooks.
externalDocs:
  description: Find out more about Debbie here
  url: https://debbiecollect.com
paths:
  /v1/{tenantId}/interactions:
    post:
      tags:
        - Interactions
      summary: Create interaction
      description: >-
        Create an interaction on a case. Use this to register an incoming
        message from a debtor or another party, for example a submitted contact
        form.
      operationId: create-interaction
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
            format: uuid
          required: true
          description: Id of the tenant
      requestBody:
        description: New interaction body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewInteraction'
            examples:
              debtor-note-mapped:
                summary: Debtor note on a case
                value:
                  type: DEBTOR NOTE
                  direction: INCOMING
                  state: MAPPED
                  referenceId: 601c0509-9b09-4e97-b380-2a67a1a08f66
                  referenceType: case
                  notes: >-
                    <p>Name: Hans Hansen</p><p>Message: I was not the driver of
                    the vehicle.</p>
                  details:
                    name: Hans Hansen
                    message: I was not the driver of the vehicle.
                  minVisibilityRole: client
              debtor-note-unmapped:
                summary: Debtor note without a matched case
                value:
                  type: DEBTOR NOTE
                  direction: INCOMING
                  state: UNMAPPED
                  referenceId: null
                  referenceType: null
                  notes: >-
                    <p>Name: Hans Hansen</p><p>Message: I was not the driver of
                    the vehicle.</p>
                  details:
                    name: Hans Hansen
                    message: I was not the driver of the vehicle.
                  minVisibilityRole: client
              note:
                summary: Internal note on a case
                value:
                  type: NOTE
                  direction: OUTGOING
                  referenceId: 601c0509-9b09-4e97-b380-2a67a1a08f66
                  referenceType: case
                  notes: <p>Called the debtor, no answer.</p>
                  details: {}
                  minVisibilityRole: caseworker
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Id of the created interaction
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
components:
  schemas:
    NewInteraction:
      oneOf:
        - $ref: '#/components/schemas/NewDebtorNoteInteraction'
        - $ref: '#/components/schemas/NewNoteInteraction'
        - $ref: '#/components/schemas/NewClientNoteInteraction'
        - $ref: '#/components/schemas/NewEmailInteraction'
        - $ref: '#/components/schemas/NewSmsInteraction'
        - $ref: '#/components/schemas/NewLetterInteraction'
        - $ref: '#/components/schemas/NewDigitalPostInteraction'
        - $ref: '#/components/schemas/NewPhoneInteraction'
        - $ref: '#/components/schemas/NewAutoCallInteraction'
        - $ref: '#/components/schemas/NewEInvoiceInteraction'
      discriminator:
        propertyName: type
        mapping:
          DEBTOR NOTE:
            $ref: '#/components/schemas/NewDebtorNoteInteraction'
          NOTE:
            $ref: '#/components/schemas/NewNoteInteraction'
          PERSONAL:
            $ref: '#/components/schemas/NewNoteInteraction'
          OTHER:
            $ref: '#/components/schemas/NewNoteInteraction'
          CLIENT NOTE:
            $ref: '#/components/schemas/NewClientNoteInteraction'
          EMAIL:
            $ref: '#/components/schemas/NewEmailInteraction'
          SMS:
            $ref: '#/components/schemas/NewSmsInteraction'
          LETTER:
            $ref: '#/components/schemas/NewLetterInteraction'
          EBOKS:
            $ref: '#/components/schemas/NewDigitalPostInteraction'
          KIVRA:
            $ref: '#/components/schemas/NewDigitalPostInteraction'
          DIGIPOST:
            $ref: '#/components/schemas/NewDigitalPostInteraction'
          PHONE:
            $ref: '#/components/schemas/NewPhoneInteraction'
          AUTO CALL:
            $ref: '#/components/schemas/NewAutoCallInteraction'
          EINVOICE:
            $ref: '#/components/schemas/NewEInvoiceInteraction'
      description: >-
        A new interaction. The shape of details depends on the type. For
        integrations registering messages from debtors or other parties, use the
        Debtor note variant.
    NewDebtorNoteInteraction:
      title: Debtor note
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - DEBTOR NOTE
              description: >-
                A message from a debtor or another party, for example a
                submitted contact form.
            details:
              type: object
              additionalProperties: true
              description: >-
                Free-form structured data about the message, for example the
                fields of a submitted form.
    NewNoteInteraction:
      title: Note
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - NOTE
                - PERSONAL
                - OTHER
              description: >-
                An internal note (NOTE), a personal contact (PERSONAL) or
                another kind of interaction (OTHER). The content goes in the
                notes field.
            details:
              type: object
              description: No details. Send an empty object.
    NewClientNoteInteraction:
      title: Client note
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - CLIENT NOTE
              description: >-
                A note to or from the creditor (client). The content goes in the
                notes field.
            details:
              type: object
              properties:
                recipients:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: >-
                    Ids of the client users to notify. At most 50 unique
                    recipients.
              description: Details of the client note.
    NewEmailInteraction:
      title: Email
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - EMAIL
              description: An email.
            details:
              type: object
              required:
                - server
                - from
                - to
              properties:
                server:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Id of the email server to send from. Null for incoming
                    emails.
                imapId:
                  type:
                    - string
                    - 'null'
                  description: IMAP id of the email
                subject:
                  type: string
                  description: Subject of the email
                from:
                  type: string
                  description: From address
                to:
                  type: string
                  description: To address
                cc:
                  type:
                    - string
                    - 'null'
                  description: CC addresses
                bcc:
                  type:
                    - string
                    - 'null'
                  description: BCC addresses
                replyTo:
                  type:
                    - string
                    - 'null'
                  description: Reply-to address
                body:
                  type: string
                  description: Plain text body
                html:
                  type:
                    - string
                    - 'null'
                  description: HTML body
                inReplyTo:
                  type:
                    - string
                    - 'null'
                  description: Message id this email replies to
                references:
                  type:
                    - string
                    - 'null'
                  description: Referenced message ids
              description: Details of the email.
    NewSmsInteraction:
      title: SMS
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - SMS
              description: An SMS.
            details:
              type: object
              required:
                - from
                - number
                - countryCode
              properties:
                from:
                  type: string
                  description: Sender name or number
                number:
                  type: string
                  description: Recipient phone number
                countryCode:
                  type: string
                  description: Recipient country code. For example 45.
                text:
                  type: string
                  description: Text of the SMS
                data:
                  type: object
                  additionalProperties: true
                  description: Provider-specific data
              description: Details of the SMS.
    NewLetterInteraction:
      title: Letter
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - LETTER
              description: A physical letter.
            details:
              oneOf:
                - title: Generated letter
                  type: object
                  required:
                    - address
                  properties:
                    address:
                      anyOf:
                        - $ref: '#/components/schemas/Address'
                        - type: 'null'
                      description: Address of the recipient
                    body:
                      type: string
                      description: Body of the letter
                    pageCount:
                      type: number
                      description: Number of pages
                - title: Existing PDF
                  type: object
                  required:
                    - pdf
                  properties:
                    pdf:
                      type: string
                      description: Id of the PDF file to send
              description: Details of the letter.
    NewDigitalPostInteraction:
      title: Digital post
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - EBOKS
                - KIVRA
                - DIGIPOST
              description: >-
                A digital post message through e-Boks (DK), Kivra (SE) or
                Digipost (NO).
            details:
              type: object
              required:
                - recipient
              properties:
                title:
                  type: string
                  description: Title of the message
                pdf:
                  type: string
                  description: Id of the PDF file to send
                button:
                  type:
                    - object
                    - 'null'
                  properties:
                    title:
                      type: string
                    description:
                      type: string
                    url:
                      type: string
                  description: Optional action button in the message
                recipient:
                  oneOf:
                    - title: KVHX
                      type: object
                      required:
                        - type
                        - firstName
                        - lastName
                        - kvhx
                      properties:
                        type:
                          type: string
                          enum:
                            - KVHX
                        firstName:
                          type: string
                        lastName:
                          type: string
                        kvhx:
                          type:
                            - string
                            - 'null'
                    - title: Central register id
                      type: object
                      required:
                        - type
                        - centralRegisterId
                        - isCompany
                      properties:
                        type:
                          type: string
                          enum:
                            - CENTRAL_REGISTER_ID
                        centralRegisterId:
                          type: string
                          description: CPR/CVR number of the recipient
                        isCompany:
                          type: boolean
                  description: The recipient of the message
                body:
                  type:
                    - string
                    - 'null'
                  description: Body of the message
              description: Details of the digital post message.
    NewPhoneInteraction:
      title: Phone call
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - PHONE
              description: A phone call. The summary goes in the notes field.
            details:
              type: object
              required:
                - phone
                - tags
              properties:
                phone:
                  type:
                    - object
                    - 'null'
                  properties:
                    number:
                      type: string
                      description: Phone number. For example 12345678.
                    locale:
                      type: string
                      description: Phone locale. For example 45.
                  description: The phone number that was called
                tags:
                  type:
                    - array
                    - 'null'
                  items:
                    type: object
                    required:
                      - tag
                    properties:
                      tag:
                        type: string
                  description: Tags describing the call
              description: Details of the phone call.
    NewAutoCallInteraction:
      title: Auto call
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - AUTO CALL
              description: An automated phone call.
            details:
              type: object
              required:
                - fromCountryCode
                - fromPhoneNumber
                - toCountryCode
                - toPhoneNumber
                - voiceName
                - actions
              properties:
                fromCountryCode:
                  type: string
                fromPhoneNumber:
                  type: string
                toCountryCode:
                  type: string
                toPhoneNumber:
                  type: string
                transcript:
                  type: string
                  description: Transcript of the call
                voiceName:
                  type: string
                  description: Name of the voice used
                actions:
                  type: array
                  items:
                    type: object
                    required:
                      - procedureId
                      - id
                    properties:
                      procedureId:
                        type: string
                      id:
                        type: string
              description: Details of the automated call.
    NewEInvoiceInteraction:
      title: E-invoice
      allOf:
        - $ref: '#/components/schemas/NewInteractionCommon'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - EINVOICE
              description: An electronic invoice. Used internally by the platform.
            details:
              type: object
              required:
                - vouchers
                - sender
                - receiver
                - collectorPaymentOptions
              properties:
                vouchers:
                  type: array
                  items:
                    type: object
                  description: Case vouchers on the invoice
                sender:
                  type: object
                  description: Sproom sender
                receiver:
                  type: object
                  description: Sproom receiver
                collectorPaymentOptions:
                  type: array
                  items:
                    type: object
                  description: Payment options of the collector
              description: Details of the e-invoice. Used internally by the platform.
    NewInteractionCommon:
      type: object
      required:
        - direction
        - minVisibilityRole
      properties:
        direction:
          type: string
          enum:
            - INCOMING
            - OUTGOING
          description: >-
            The direction of the interaction. Use INCOMING for messages received
            from a debtor or another party.
        state:
          type: string
          enum:
            - UNMAPPED
            - MAPPED
            - HANDLED
            - DELETED
            - PENDING
            - QUEUED
            - SENT
            - CANCELLED
          description: >-
            The state of the interaction. For INCOMING interactions use MAPPED
            when referenceId is set and UNMAPPED when the interaction could not
            be matched to a case (HANDLED and DELETED are set by caseworkers).
            PENDING, QUEUED, SENT and CANCELLED apply to OUTGOING interactions.
            Defaults to MAPPED/UNMAPPED for incoming interactions based on
            referenceId.
        referenceId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Id of the entity the interaction belongs to, typically a case id.
            Can be null if the interaction could not be matched to a case.
        referenceType:
          type:
            - string
            - 'null'
          enum:
            - debtor
            - case
            - tribunal-case
            - creditor
            - customer
            - collector
            - case-voucher
            - billing-voucher
            - billing
            - workflow
            - template
            - null
          description: The type of the reference. Use case when referenceId is a case id.
        notes:
          type:
            - string
            - 'null'
          description: >-
            The content of the interaction as HTML. The HTML is sanitized server
            side.
        minVisibilityRole:
          type: string
          enum:
            - alternative-contact
            - debtor
            - client
            - caseworker
            - admin
            - super-admin
          description: >-
            The minimum role that can see the interaction. Use client if the
            interaction should be visible to the creditor but not the debtor.
        attachments:
          type:
            - array
            - 'null'
          items:
            oneOf:
              - type: string
                format: uuid
                description: Id of a file to attach
              - $ref: '#/components/schemas/File'
          description: >-
            Files to attach to the interaction, as file ids or file objects.
            Files can be uploaded with the create file endpoint and must belong
            to the tenant.
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Time the interaction was created. Defaults to now.
    Address:
      type: object
      properties:
        address:
          type: string
          description: The street name and number of the address
        coAddress:
          type: string
        zipcode:
          type: string
        city:
          type: string
        country:
          type: string
      required:
        - address
        - zipcode
        - city
    File:
      type: object
      properties:
        fileName:
          type: string
        contentType:
          type: string
        fileId:
          type: string
          format: uuid
      required:
        - fileName
        - contentType
        - fileId
  responses:
    UnauthorizedError:
      description: Access token missing or invalid
    UnprocessableContent:
      description: Unable to process the contained instructions.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authentication can be done by using a bearer token in the Authorization
        header. This is done using the following format `Authorization: Bearer
        {token}`.

````