Grain Vendors API

openapi: 3.2.0
info:
  title: Grain Vendors API
  version: 1.0.0
  description: Grain's API provides a comprehensive set of endpoints for managing hedging, currency conversions, pricing, and fund movements - enabling seamless integration of FX workflows into your platform. Each API call follows REST conventions, uses secure authentication, and returns standardized responses for consistency across environments.
  license:
    name: Creative Commons Attribution 3.0
  contact:
    name: Grain Finance
    url: https://docs.grainfinance.co
    email: support@grainfinance.co
  termsOfService: https://grainfinance.co/terms-of-service/
  x-apiClientRegistration:
    url: https://grainfinance.co/partners
servers:
- url: https://api.grainfinance.co/v1
  description: Grain API
tags:
- name: Vendors
  description: Vendor objects represent payees that payouts can be sent to. A vendor holds contact details and one or more payout methods — the bank accounts payouts are sent to.
paths:
  /vendors/{vendorId}:
    get:
      operationId: Get
      responses:
        '200':
          description: Vendor found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerVendor'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The request failed because an upstream provider was unavailable or returned an unexpected response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Retrieves a single vendor by its vendor id, including its contact details and payout methods.
      tags:
      - Vendors
      security:
      - api-key: []
      parameters:
      - description: The id of the vendor within the Grain platform.
        in: path
        name: vendorId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      summary: Get
      x-summary-source: derived
  /vendors:
    post:
      operationId: Create
      responses:
        '201':
          description: Vendor created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerVendor'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The request failed because an upstream provider was unavailable or returned an unexpected response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: 'Creates a vendor with a single payout method.

        The bank account fields required in `payoutMethod` depend on the method''s currency, bank country and type.'
      tags:
      - Vendors
      security:
      - api-key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVendorRequest'
      summary: Create
      x-summary-source: derived
    get:
      operationId: List
      responses:
        '200':
          description: Vendors found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorListResponse'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The request failed because an upstream provider was unavailable or returned an unexpected response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Lists the partner's vendors, ordered by name, including their contact details and payout methods.
      tags:
      - Vendors
      security:
      - api-key: []
      parameters:
      - description: Filters vendors whose name contains the given text, case-insensitive.
        in: query
        name: name
        required: false
        schema:
          type: string
      - in: query
        name: page
        required: false
        schema:
          $ref: '#/components/schemas/Page'
      - in: query
        name: per_page
        required: false
        schema:
          $ref: '#/components/schemas/PerPage'
      summary: List
      x-summary-source: derived
components:
  schemas:
    VendorContact:
      description: 'The contact details of the vendor. Conditional fields (`state`, `taxId`, `phoneNumber`,

        `companyRegisterNumber`) are returned only when they were provided.'
      properties:
        fullName:
          type: string
          description: The full name of the vendor's contact person or business.
          example: Acme Supplies Ltd
        country:
          $ref: '#/components/schemas/CountryCode'
          description: The alpha-2 ISO 3166 country code of the vendor.
          example: US
        city:
          type: string
          description: The city of the vendor's address.
          example: New York
        email:
          type: string
          description: The email address of the vendor, when provided.
          example: billing@acmesupplies.com
        streetName:
          type: string
          description: The street name of the vendor's address, when provided.
          example: Madison Avenue
        buildingName:
          type: string
          description: The building name or number of the vendor's address, when provided.
          example: '383'
        postalCode:
          type: string
          description: The postal code of the vendor's address, when provided.
          example: '10017'
        state:
          type: string
          description: The ISO state code of the vendor's address, when provided. Required for vendors in US, CA, NZ and AU.
          example: NY
        taxId:
          type: string
          description: The tax id of the vendor, when provided.
          example: '901234567'
        phoneNumber:
          type: string
          description: The phone number of the vendor's contact, when provided.
          example: '+13212312321'
        companyRegisterNumber:
          type: string
          description: The company register number of the vendor, when provided.
          example: '514455544'
      required:
      - fullName
      - country
      - city
      type: object
      additionalProperties: false
    VendorPayoutMethod:
      description: 'A payout method registered for the vendor — the bank account payouts in `currency` are sent to.

        Bank account fields are corridor-specific: only the fields relevant to the method''s currency,

        country, and type are returned.'
      properties:
        type:
          $ref: '#/components/schemas/DisplayPaymentMethod'
          description: The payment method used to send payouts to this bank account.
          example: SEPA
        currency:
          $ref: '#/components/schemas/CurrencyCode'
          description: The alpha-3 ISO 4217 currency code of payouts sent with this method.
          example: EUR
        bankName:
          type: string
          description: The name of the bank holding the account.
          example: JPMorgan Chase Bank, N.A.
        bankCountry:
          $ref: '#/components/schemas/CountryCode'
          description: The alpha-2 ISO 3166 country code of the bank.
          example: US
        bankState:
          type: string
          description: The ISO state code of the bank's location, when applicable.
          example: NY
        accountNumber:
          type: string
          description: The account number, when applicable.
          example: '8290041523'
        iban:
          type: string
          description: The IBAN of the account, when applicable.
          example: DE89370400440532013000
          pattern: ^[A-Z0-9]{15,34}$
        bicSwift:
          type: string
          description: The SWIFT/BIC code of the bank, when applicable.
          example: CHASUS33XXX
          pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
        routingCode:
          type: string
          description: Country-specific routing code, when applicable — the nine-digit ABA routing number for USD payouts.
          example: '021000021'
        bankCode:
          type: string
          description: Country-specific bank code, when applicable — CAD (EFT), HKD (CCASS), SGD (IBG) and MXN (SPEI) payouts.
          example: '004'
        branchCode:
          type: string
          description: Country-specific branch code, when applicable — CAD (EFT), HKD (CCASS), SGD (IBG) and MXN (SPEI) payouts.
          example: 081
        sortCode:
          type: string
          description: UK sort code, when applicable. Six digits, no hyphens.
          example: '560036'
          pattern: ^\d{6}$
        bsbCode:
          type: string
          description: Australian BSB code, when applicable. Six digits, no hyphens.
          example: 082902
          pattern: ^\d{6}$
        bankAddress:
          type: string
          description: The full address of the bank, when provided.
          example: 383 Madison Avenue, New York, NY 10017
      required:
      - type
      - currency
      - bankName
      - bankCountry
      type: object
      additionalProperties: false
    ErrorResponse:
      description: An API Error
      properties:
        message:
          type: string
          description: A short explanation of the error.
          example: Can't perform this action
        reason:
          type: string
          description: A detailed description of the reason for the failure.
          example: Supplied object is in *Cancelled* state, which prevents performing this action
      required:
      - message
      type: object
      additionalProperties: false
    DisplayPaymentMethod:
      enum:
      - SWIFT
      - SEPA
      - WIRE
      - ACH
      - FPS
      - CA ACSS
      - NPP
      - IBG
      - BECS
      - CCASS
      - TEF
      - UAEFTS
      - SIC
      - CERTIS
      - DKSMC
      - NICS
      - SORBNET
      - RIX
      - SAMOS
      - ZAHAV
      - SARIE
      - QPS
      type: string
    PerPage:
      type: number
      format: double
      description: number of items in a page
      minimum: 1
      maximum: 100
    CustomerVendor:
      description: 'A Vendor represents a payee that payouts can be sent to. Returned by `POST /v1/vendors`,

        `GET /v1/vendors/{vendorId}`, and `GET /v1/vendors`.'
      properties:
        vendorId:
          $ref: '#/components/schemas/UUID'
          description: The id of the vendor within the Grain platform.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        externalVendorId:
          $ref: '#/components/schemas/ExternalVendorId'
          description: The vendor id, as identified within your system.
          example: vendor_001
        contact:
          $ref: '#/components/schemas/VendorContact'
          description: The contact details of the vendor.
        payoutMethods:
          items:
            $ref: '#/components/schemas/VendorPayoutMethod'
          type: array
          description: The payout methods registered for the vendor.
        createdAt:
          $ref: '#/components/schemas/IsoDateTime'
          description: When the vendor was created, as an ISO-8601 date-time in UTC.
          example: '2026-05-15T09:12:28.000Z'
        updatedAt:
          $ref: '#/components/schemas/IsoDateTime'
          description: When the vendor was last updated, as an ISO-8601 date-time in UTC.
          example: '2026-05-15T09:12:28.000Z'
      required:
      - vendorId
      - externalVendorId
      - contact
      - payoutMethods
      - createdAt
      - updatedAt
      type: object
      additionalProperties: false
    PaginationResponse:
      description: Pagination parameters of the returned results.
      properties:
        page:
          $ref: '#/components/schemas/Page'
        perPage:
          $ref: '#/components/schemas/PerPage'
        totalResults:
          type: number
          format: double
          description: The total amount of results available
      required:
      - page
      - perPage
      - totalResults
      type: object
      additionalProperties: false
    CountryCode:
      type: string
      example: GB
      description: The alpha-2 ISO 3166 country code of the entity's country.
      pattern: ^[A-Za-z]{2}$
    VendorListResponse:
      description: A paginated list of vendors.
      properties:
        vendors:
          items:
            $ref: '#/components/schemas/CustomerVendor'
          type: array
          description: A list of vendors, ordered by name.
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      required:
      - vendors
      - pagination
      type: object
      additionalProperties: false
    UUID:
      type: string
      format: uuid
      pattern: '[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}'
    Page:
      type: number
      format: double
      description: The page indicating which set of items are returned
      minimum: 1
    ExternalVendorId:
      type: string
      example: vendor_001
      description: Partner's own reference ID for the vendor.
      pattern: ^[A-Za-z0-9_.\-]{1,64}$
    IsoDateTime:
      type: string
      example: '2026-05-15T09:12:28.000Z'
      format: date-time
      description: An ISO-8601 date-time string in UTC.
    CreateVendorRequest:
      description: 'Request body for `POST /v1/vendors`. Creates a vendor with a single payout method. The conditional

        contact fields (`contactState`, `contactTaxId`, `contactPhoneNumber`, `companyRegisterNumber`) are

        required for some countries.'
      properties:
        externalVendorId:
          $ref: '#/components/schemas/ExternalVendorId'
          description: The vendor id, as identified within your system.
          example: vendor_001
        contactFullName:
          type: string
          description: The full name of the vendor's contact person or business.
          example: Acme Supplies Ltd
        contactCountry:
          $ref: '#/components/schemas/CountryCode'
          description: The alpha-2 ISO 3166 country code of the vendor.
          example: US
        contactCity:
          type: string
          description: The city of the vendor's address.
          example: New York
        contactEmail:
          type: string
          description: The email address of the vendor.
          example: billing@acmesupplies.com
        contactStreetName:
          type: string
          description: The street name of the vendor's address.
          example: Madison Avenue
        contactBuildingName:
          type: string
          description: The building name or number of the vendor's address.
          example: '383'
        contactPostalCode:
          type: string
          description: The postal code of the vendor's address.
          example: '10017'
        contactState:
          type: string
          description: The ISO state code of the vendor's address. Required for vendors in US, CA, NZ and AU.
          example: NY
        contactTaxId:
          type: string
          description: The tax id of the vendor. Required for vendors in some countries.
          example: '901234567'
        contactPhoneNumber:
          type: string
          description: The phone number of the vendor's contact. Required for vendors in some countries.
          example: '+13212312321'
        companyRegisterNumber:
          type: string
          description: The company register number of the vendor. Required for vendors in some countries.
          example: '514455544'
        payoutMethod:
          $ref: '#/components/schemas/VendorPayoutMethod'
          description: The payout method to register for the vendor.
      required:
      - externalVendorId
      - contactFullName
      - contactCountry
      - contactCity
      - contactEmail
      - contactStreetName
      - contactBuildingName
      - contactPostalCode
      - payoutMethod
      type: object
      additionalProperties: false
    CurrencyCode:
      type: string
      example: EUR
      description: The alpha-3 ISO 4217 currency code of the related entity, in upper case.
      pattern: ^[A-Z]{3}$
  securitySchemes:
    api-key:
      type: http
      scheme: basic
      description: Basic authentication using the partner API keys from https://console.grainfinance.co/keys