Airtm Embedded Senders API

openapi: 3.2.0
info:
  title: Airtm Enterprise API V2 Embedded Senders API
  version: 1.155.0
  description: '# Introduction


    The Airtm Enterprise API enables organizations to send and receive payments globally through a simple REST API.'
  contact:
    name: Airtm Enterprise
    email: enterprise@airtm.com
    url: https://www.airtm.com
servers:
- url: https://api.enterprise.airtm.com/v2
- url: https://api.stg.enterprise.airtm.com/v2
tags:
- name: Embedded Senders
paths:
  /embedded/senders:
    post:
      operationId: CreateSender
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenderApiResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: Create a new embedded sender for the authenticated partner.
      summary: Create sender
      tags:
      - Embedded Senders
      security:
      - embeddedAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSenderRequest'
            example:
              externalSenderId: your-own-controlled-id
              partyType: individual
              countryOfResidence: VEN
              enabledFundingRailIds:
              - stellar.usdc
              individual:
                firstName: $first_name
                lastName: $last_name
                dob: '1990-01-01'
                nationalIdNumber: $national_id_number
                nationality: VEN
              contact:
                email: $email
                phoneNumber: $phone_number
                phoneCountryCode: $phone_country_code
              address:
                line1: $address_line1
                city: $address_city
                region: $address_region
                postalCode: $address_postal_code
                country: $address_country
              compliance:
                kycReliance:
                  performedBy: $kyc_reliance_performed_by
                  kycReferenceId: $kyc_reliance_kyc_reference_id
                  status: VERIFIED
                  performedAt: '2026-04-29T12:00:00.000Z'
                  level: FULL
                  documentType: PASSPORT
                  provider:
                    name: $kyc_reliance_provider_name
                    applicantId: $kyc_reliance_provider_applicant_id
                    result: GREEN
                screening:
                  sanctionsHit: false
                  pepHit: false
                  adverseMediaHit: false
                  riskRating: LOW
                  screenedAt: '2026-04-29T12:00:00.000Z'
                sessionContext:
                  ipAddress: 127.0.0.1
                  userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36
                  deviceId: '1234567890'
    get:
      operationId: GetSenderByExternalId
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenderApiResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: Retrieve a sender by its external identifier.
      summary: Get sender by external id
      tags:
      - Embedded Senders
      security:
      - embeddedAuth: []
      parameters:
      - description: The external sender identifier provided by the partner.
        in: query
        name: externalSenderId
        required: true
        schema:
          type: string
  /embedded/senders/{senderId}:
    get:
      operationId: GetSenderById
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenderApiResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: Retrieve a sender by its id.
      summary: Get sender by id
      tags:
      - Embedded Senders
      security:
      - embeddedAuth: []
      parameters:
      - description: The sender id.
        in: path
        name: senderId
        required: true
        schema:
          type: string
    put:
      operationId: UpdateSenderById
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenderApiResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: Update an existing sender.
      summary: Update sender
      tags:
      - Embedded Senders
      security:
      - embeddedAuth: []
      parameters:
      - description: The sender id.
        in: path
        name: senderId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSenderRequest'
components:
  schemas:
    CreateSenderContact:
      description: Contact information for the sender.
      properties:
        email:
          type: string
          pattern: ^(.+)@(.+)$
        phoneNumber:
          type: string
        phoneCountryCode:
          type: string
          pattern: ^\+\d{1,3}$
      required:
      - email
      - phoneNumber
      - phoneCountryCode
      type: object
      additionalProperties: false
    KycLevel:
      enum:
      - BASIC
      - FULL
      type: string
      x-enum-varnames:
      - BASIC
      - FULL
    Record_string.unknown_:
      properties: {}
      additionalProperties: {}
      type: object
      description: Construct a type with a set of properties K of type T
    CreateSenderKycReliance:
      description: KYC reliance information from the partner's KYC provider.
      properties:
        performedBy:
          type: string
        kycReferenceId:
          type: string
        status:
          $ref: '#/components/schemas/KycStatus'
        performedAt:
          type: string
        level:
          $ref: '#/components/schemas/KycLevel'
        documentType:
          $ref: '#/components/schemas/DocumentType'
        provider:
          properties:
            result:
              $ref: '#/components/schemas/ProviderResult'
            applicantId:
              type: string
            name:
              type: string
          required:
          - result
          - applicantId
          - name
          type: object
      required:
      - performedBy
      - kycReferenceId
      - status
      - performedAt
      - level
      - documentType
      - provider
      type: object
      additionalProperties: false
    Partial_CreateSenderCompliance_:
      properties:
        kycReliance:
          $ref: '#/components/schemas/CreateSenderKycReliance'
        screening:
          $ref: '#/components/schemas/Screening'
        sessionContext:
          $ref: '#/components/schemas/SessionContext'
      type: object
      description: Make all properties in T optional
    RiskRating:
      enum:
      - LOW
      - MEDIUM
      - HIGH
      type: string
      x-enum-varnames:
      - LOW
      - MEDIUM
      - HIGH
    DocumentType:
      enum:
      - PASSPORT
      - NATIONAL_ID
      - DRIVER_LICENSE
      type: string
      x-enum-varnames:
      - PASSPORT
      - NATIONAL_ID
      - DRIVER_LICENSE
    CreateSenderAddress:
      description: Address information for the sender.
      properties:
        line1:
          type: string
        city:
          type: string
        region:
          type: string
        postalCode:
          type: string
        country:
          type: string
          description: Country code 3 letter ISO code.
          minLength: 3
          maxLength: 3
      required:
      - line1
      - city
      - region
      - postalCode
      - country
      type: object
      additionalProperties: false
    ProviderResult:
      enum:
      - GREEN
      - AMBER
      - RED
      type: string
      x-enum-varnames:
      - GREEN
      - AMBER
      - RED
    Partial_UpdateSenderContact_:
      properties:
        phoneNumber:
          type: string
        phoneCountryCode:
          type: string
          pattern: ^\+\d{1,3}$
      type: object
      description: Make all properties in T optional
    FundingRailId:
      enum:
      - stellar.usdc
      type: string
      x-enum-varnames:
      - STELLAR_USDC
    Screening:
      properties:
        sanctionsHit:
          type: boolean
          description: 'true = a sanctions match was found during partner screening.

            false = the user was screened and no sanctions match was found.'
        pepHit:
          type: boolean
          description: 'true = a PEP match was found during partner screening.

            false = the user was screened and no PEP match was found.'
        adverseMediaHit:
          type: boolean
          description: 'true = an adverse media match was found during partner screening.

            false = the user was screened and no adverse media match was found.'
        riskRating:
          $ref: '#/components/schemas/RiskRating'
        screenedAt:
          type: string
      required:
      - sanctionsHit
      - pepHit
      - adverseMediaHit
      - riskRating
      - screenedAt
      type: object
      additionalProperties: false
    KycStatus:
      enum:
      - VERIFIED
      - PARTIALLY_VERIFIED
      - NOT_VERIFIED
      type: string
      x-enum-varnames:
      - VERIFIED
      - PARTIALLY_VERIFIED
      - NOT_VERIFIED
    Partial_CreateSenderAddress_:
      properties:
        line1:
          type: string
        city:
          type: string
        region:
          type: string
        postalCode:
          type: string
        country:
          type: string
          description: Country code 3 letter ISO code.
          minLength: 3
          maxLength: 3
      type: object
      description: Make all properties in T optional
    UpdateSenderRequest:
      properties:
        partyType:
          type: string
          enum:
          - individual
          - business
          description: 'The type of party: individual or business.'
          pattern: ^(individual|business)$
        countryOfResidence:
          type: string
          description: Country code 3 letter ISO code.
          minLength: 3
          maxLength: 3
        enabledFundingRailIds:
          items:
            type: string
          type: array
          description: List of funding rail IDs to enable for this sender.
        individual:
          $ref: '#/components/schemas/Partial_CreateSenderIndividual_'
          description: Individual party details (all fields optional for partial update).
        contact:
          $ref: '#/components/schemas/Partial_UpdateSenderContact_'
          description: Contact information (phone can be updated; email is immutable).
        address:
          $ref: '#/components/schemas/Partial_CreateSenderAddress_'
          description: Address information (all fields optional for partial update).
        compliance:
          $ref: '#/components/schemas/Partial_CreateSenderCompliance_'
          description: Compliance and KYC reliance information (partial update).
      type: object
      additionalProperties: false
    CreateSenderCompliance:
      properties:
        kycReliance:
          $ref: '#/components/schemas/CreateSenderKycReliance'
        screening:
          $ref: '#/components/schemas/Screening'
        sessionContext:
          $ref: '#/components/schemas/SessionContext'
      required:
      - kycReliance
      - screening
      - sessionContext
      type: object
      additionalProperties: false
    Partial_CreateSenderIndividual_:
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dob:
          type: string
        nationalIdNumber:
          type: string
        nationality:
          type: string
      type: object
      description: Make all properties in T optional
    SenderApiResponse:
      properties:
        id:
          type: string
        externalSenderId:
          type: string
        partyType:
          type: string
          enum:
          - individual
          - business
        countryOfResidence:
          type: string
        individual:
          properties:
            nationality:
              type: string
            nationalIdNumber:
              type: string
            dob:
              type: string
            lastName:
              type: string
            firstName:
              type: string
          required:
          - nationality
          - nationalIdNumber
          - dob
          - lastName
          - firstName
          type: object
        contact:
          properties:
            phoneCountryCode:
              type: string
            phoneNumber:
              type: string
            email:
              type: string
          required:
          - phoneCountryCode
          - phoneNumber
          - email
          type: object
        address:
          properties:
            country:
              type: string
            postalCode:
              type: string
            region:
              type: string
            city:
              type: string
            line1:
              type: string
          required:
          - country
          - postalCode
          - region
          - city
          - line1
          type: object
        compliance:
          properties:
            sessionContext:
              properties:
                deviceId:
                  type: string
                userAgent:
                  type: string
                ipAddress:
                  type: string
              required:
              - deviceId
              - userAgent
              - ipAddress
              type: object
            screening:
              properties:
                screenedAt:
                  type: string
                riskRating:
                  $ref: '#/components/schemas/RiskRating'
                adverseMediaHit:
                  type: boolean
                pepHit:
                  type: boolean
                sanctionsHit:
                  type: boolean
              required:
              - screenedAt
              - riskRating
              - adverseMediaHit
              - pepHit
              - sanctionsHit
              type: object
            kycReliance:
              properties:
                provider:
                  properties:
                    result:
                      type: string
                    applicantId:
                      type: string
                    name:
                      type: string
                  required:
                  - result
                  - applicantId
                  - name
                  type: object
                documentType:
                  $ref: '#/components/schemas/DocumentType'
                level:
                  type: string
                performedAt:
                  type: string
                status:
                  type: string
                kycReferenceId:
                  type: string
                performedBy:
                  type: string
              required:
              - provider
              - documentType
              - level
              - performedAt
              - status
              - kycReferenceId
              - performedBy
              type: object
          required:
          - sessionContext
          - screening
          - kycReliance
          type: object
        fundingRailInstances:
          items:
            properties:
              data:
                $ref: '#/components/schemas/Record_string.unknown_'
              type:
                type: string
                enum:
                - CRYPTO
                - FIAT
              railId:
                type: string
            required:
            - data
            - type
            - railId
            type: object
          type: array
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
      - id
      - externalSenderId
      - partyType
      - countryOfResidence
      - individual
      - contact
      - address
      - compliance
      - fundingRailInstances
      - createdAt
      - updatedAt
      type: object
      additionalProperties: false
    CreateSenderIndividual:
      description: Individual party details. Required when partyType is 'individual'.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dob:
          type: string
        nationalIdNumber:
          type: string
        nationality:
          type: string
      required:
      - firstName
      - lastName
      - dob
      - nationalIdNumber
      - nationality
      type: object
      additionalProperties: false
    CreateSenderRequest:
      properties:
        externalSenderId:
          type: string
          description: The unique identifier for this sender in the partner's system.
        partyType:
          type: string
          enum:
          - individual
          - business
          description: 'The type of party: individual or business.'
          pattern: ^(individual|business)$
        countryOfResidence:
          type: string
          description: Country code 3 letter ISO code.
          minLength: 3
          maxLength: 3
        enabledFundingRailIds:
          items:
            $ref: '#/components/schemas/FundingRailId'
          type: array
          description: List of funding rail IDs to enable for this sender.
          default: []
        individual:
          $ref: '#/components/schemas/CreateSenderIndividual'
          description: Individual party details. Required when partyType is 'individual'.
        contact:
          $ref: '#/components/schemas/CreateSenderContact'
          description: Contact information.
        address:
          $ref: '#/components/schemas/CreateSenderAddress'
          description: Address information.
        compliance:
          $ref: '#/components/schemas/CreateSenderCompliance'
          description: Compliance and KYC reliance information.
      required:
      - externalSenderId
      - partyType
      - countryOfResidence
      - individual
      - contact
      - address
      - compliance
      type: object
      additionalProperties: false
    SessionContext:
      properties:
        ipAddress:
          type: string
        userAgent:
          type: string
        deviceId:
          type: string
      required:
      - ipAddress
      - userAgent
      - deviceId
      type: object
      additionalProperties: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-tagGroups:
- name: Payout Operations
  tags:
  - Payouts
  - Bulk Payouts
  - Users
- name: Payin Operations
  tags:
  - Payins
- name: Account
  tags:
  - Me
  - Deposits
  - Reports
- name: Direct Withdrawal
  tags:
  - External Bank Account
  - External Crypto Account
  - Withdrawals
- name: Webhooks
  tags:
  - Webhooks