find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/grainfinance-co:grainfinance-co-customers-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Grain Customers 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: Customers
  description: Customer objects represent your end customers on the Grain platform. A customer must be created before a hedge or conversion can be initiated.
paths:
  /customers:
    post:
      operationId: Create
      responses:
        '200':
          description: Customer Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateObjectResponseBody'
        '201':
          description: Customer Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateObjectResponseBody'
        '400':
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          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'
      description: Creates a new customer. If a customer with the same external ID already exists, the record is updated automatically.
      tags:
      - Customers
      security:
      - api-key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUpdateCustomerRequestBody'
      summary: Create
      x-summary-source: derived
    get:
      operationId: List
      responses:
        '200':
          description: Customer Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomersResponseBody'
      description: Retrieves a list of all existing customers.
      tags:
      - Customers
      security:
      - api-key: []
      parameters:
      - description: external_customer_id is the customer id, as identified within your system
        in: query
        name: external_customer_id
        required: false
        schema:
          type: string
      - description: page number indicating which set of items to return
        in: query
        name: page
        required: false
        schema:
          $ref: '#/components/schemas/Page'
      - description: The number of items in a page
        in: query
        name: per_page
        required: false
        schema:
          $ref: '#/components/schemas/PerPage'
      summary: List
      x-summary-source: derived
  /customers/{customerId}/update:
    post:
      operationId: Update
      responses:
        '204':
          description: Customer has been Updated
        '400':
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          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'
        '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'
      description: Updates an existing customer's information.
      tags:
      - Customers
      security:
      - api-key: []
      parameters:
      - description: The id of the customer within the Grain platform.
        in: path
        name: customerId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequestBody'
      summary: Update
      x-summary-source: derived
  /customers/{customerId}:
    get:
      operationId: Get
      responses:
        '200':
          description: Customer Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Retrieves a specific customer by its Grain customer ID.
      tags:
      - Customers
      security:
      - api-key: []
      parameters:
      - description: The UUID of the customer
        in: path
        name: customerId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      summary: Get
      x-summary-source: derived
    delete:
      operationId: Delete
      responses:
        '204':
          description: Customer has been Deleted
        '404':
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Removes a customer by ID.
      tags:
      - Customers
      security:
      - api-key: []
      parameters:
      - description: The UUID of the customer
        in: path
        name: customerId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      summary: Delete
      x-summary-source: derived
components:
  schemas:
    Customer:
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: The id of the customer within the Grain platform.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        companyName:
          type: string
          description: The legal name of the customer's company
          example: Ollivander's Wand Shop
        companyAddress:
          type: string
          description: The address of the company
          example: 12 Diagon Alley
        companyCity:
          type: string
          description: The city of the company
          example: London
        companyState:
          type: string
          description: The state the company is in (US based)
          example: London
        companyCountry:
          $ref: '#/components/schemas/CountryCode'
        contactEmail:
          $ref: '#/components/schemas/ContactEmail'
          description: The email for the company's primary contact
          example: customer@company.com
        contactFullName:
          type: string
          description: The name of the company's primary contact
          example: Garrick Ollivander
        contactPhoneNumber:
          type: string
          description: The phone number of the company's primary contact
          example: '+12125551234'
        companyTaxId:
          type: string
          description: The tax identification or registration number of the company
          example: 123-45-6789
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        status:
          $ref: '#/components/schemas/CustomerStatus'
        extraFields:
          $ref: '#/components/schemas/CustomersExtraFieldsParam'
          description: 'Additional fields that provide further details about the customer.

            These fields should be specified as a valid JSON object.'
          example:
            field_a: value_a
            field_b: value_b
      required:
      - id
      - companyName
      - companyCountry
      - externalCustomerId
      - status
      type: object
      additionalProperties: false
    CreateUpdateCustomerRequestBody:
      $ref: '#/components/schemas/Pick_Customer.-or-contactEmail-or-contactFullName-or-contactPhoneNumber-or-companyName-or-companyAddress-or-companyCity-or-companyState-or-companyCountry-or-companyTaxId-or-externalCustomerId-or-extraFields_'
      description: The payload required in order to create a customer.
    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
    CustomerStatus:
      description: The eligibility of the customer to receive quotes
      enum:
      - Pending
      - Approved
      - Rejected
      type: string
    CustomersExtraFieldsParam:
      properties: {}
      additionalProperties:
        anyOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      type: object
      example:
        field_a: value_a
        field_b: value_b
      description: 'Additional fields that provide further details about the company.

        These fields should be specified as a valid JSON object.'
    ? Pick_Customer.-or-contactEmail-or-contactFullName-or-contactPhoneNumber-or-companyName-or-companyAddress-or-companyCity-or-companyState-or-companyCountry-or-companyTaxId-or-externalCustomerId-or-extraFields_
    : properties:
        contactEmail:
          $ref: '#/components/schemas/ContactEmail'
          description: The email for the company's primary contact
          example: customer@company.com
        contactFullName:
          type: string
          description: The name of the company's primary contact
          example: Garrick Ollivander
        contactPhoneNumber:
          type: string
          description: The phone number of the company's primary contact
          example: '+12125551234'
        companyName:
          type: string
          description: The legal name of the customer's company
          example: Ollivander's Wand Shop
        companyAddress:
          type: string
          description: The address of the company
          example: 12 Diagon Alley
        companyCity:
          type: string
          description: The city of the company
          example: London
        companyState:
          type: string
          description: The state the company is in (US based)
          example: London
        companyCountry:
          $ref: '#/components/schemas/CountryCode'
        companyTaxId:
          type: string
          description: The tax identification or registration number of the company
          example: 123-45-6789
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        extraFields:
          $ref: '#/components/schemas/CustomersExtraFieldsParam'
          description: 'Additional fields that provide further details about the customer.

            These fields should be specified as a valid JSON object.'
          example:
            field_a: value_a
            field_b: value_b
      required:
      - companyName
      - companyCountry
      - externalCustomerId
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    ContactEmail:
      type: string
      example: garrick@ollivanders.co.uk
      description: The email address of the company's primary contact
    PerPage:
      type: number
      format: double
      description: number of items in a page
      minimum: 1
      maximum: 100
    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}$
    UpdateCustomerRequestBody:
      $ref: '#/components/schemas/Partial_CreateUpdateCustomerRequestBody_'
      description: The payload for updating an existing customer. Only the fields provided will be updated.
    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
    ListCustomersResponseBody:
      description: A response containing a list of customers matching the search criteria.
      properties:
        customers:
          items:
            $ref: '#/components/schemas/Customer'
          type: array
          description: A list of customers matching the search criteria.
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      required:
      - customers
      - pagination
      type: object
      additionalProperties: false
    Partial_CreateUpdateCustomerRequestBody_:
      properties:
        contactEmail:
          $ref: '#/components/schemas/ContactEmail'
          description: The email for the company's primary contact
          example: customer@company.com
        contactFullName:
          type: string
          description: The name of the company's primary contact
          example: Garrick Ollivander
        contactPhoneNumber:
          type: string
          description: The phone number of the company's primary contact
          example: '+12125551234'
        companyName:
          type: string
          description: The legal name of the customer's company
          example: Ollivander's Wand Shop
        companyAddress:
          type: string
          description: The address of the company
          example: 12 Diagon Alley
        companyCity:
          type: string
          description: The city of the company
          example: London
        companyState:
          type: string
          description: The state the company is in (US based)
          example: London
        companyCountry:
          $ref: '#/components/schemas/CountryCode'
        companyTaxId:
          type: string
          description: The tax identification or registration number of the company
          example: 123-45-6789
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        extraFields:
          $ref: '#/components/schemas/CustomersExtraFieldsParam'
          description: 'Additional fields that provide further details about the customer.

            These fields should be specified as a valid JSON object.'
          example:
            field_a: value_a
            field_b: value_b
      type: object
      description: Make all properties in T optional
    CreateObjectResponseBody:
      description: A response containing the ID of the created object.
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: The id of the created object.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
      required:
      - id
      type: object
      additionalProperties: false
  securitySchemes:
    api-key:
      type: http
      scheme: basic
      description: Basic authentication using the partner API keys from https://console.grainfinance.co/keys