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

# Create a supplier

> OAuth scope: `supplier_invoice.write`

Creates a supplier in the organization. The organization is the one the request is authenticated for; it cannot be set in the request body. New suppliers are created with the **`unarchived`** status.

Only **`name`** is required. If a supplier with the same name and IBAN already exists in the organization, it is returned instead of creating a duplicate. If the IBAN already belongs to a supplier with a different name, the call fails with **`422`**.

Sensitive fields (**`payment_details`** and **`tax_identifiers`**) are masked in the response unless the caller is allowed to see them.




## OpenAPI

````yaml post /v2/suppliers
openapi: 3.1.1
info:
  version: v2
  title: Qonto
servers:
  - url: https://thirdparty.qonto.com
    description: Production URL
  - url: https://thirdparty-sandbox.staging.qonto.co
    description: Sandbox URL
security:
  - OAuth:
      - organization.read
      - membership.read
      - membership.write
      - attachment.write
      - internal_transfer.write
      - payment.write
      - supplier_invoice.write
      - supplier_invoice.read
      - client_invoices.read
      - client_invoice.write
      - client.read
      - client.write
      - product.read
      - product.write
      - request_review.write
      - request_review.read
      - team.read
      - team.write
      - request_transfers.write
      - insurance_contract.read
      - insurance_contract.write
      - card.read
      - card.write
      - bank_account.write
      - beneficiary.trust
      - webhook
      - payment_link.write
      - payment_link.read
      - sepa_direct_debit.read
      - sepa_direct_debit.write
      - terminal.read
      - terminal.write
  - SecretKey: []
paths:
  /v2/suppliers:
    parameters:
      - $ref: '#/components/parameters/X-Qonto-Staging-Token'
    post:
      tags:
        - Suppliers
      summary: Create a supplier
      description: >
        OAuth scope: `supplier_invoice.write`


        Creates a supplier in the organization. The organization is the one the
        request is authenticated for; it cannot be set in the request body. New
        suppliers are created with the **`unarchived`** status.


        Only **`name`** is required. If a supplier with the same name and IBAN
        already exists in the organization, it is returned instead of creating a
        duplicate. If the IBAN already belongs to a supplier with a different
        name, the call fails with **`422`**.


        Sensitive fields (**`payment_details`** and **`tax_identifiers`**) are
        masked in the response unless the caller is allowed to see them.
      operationId: create_supplier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierWriteRequest'
      responses:
        '201':
          description: The created supplier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierResponse'
        '400':
          $ref: '#/components/responses/400-Bad-request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '409':
          $ref: '#/components/responses/409-Conflict'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponseBody'
              examples:
                invalid_iban:
                  summary: Invalid field
                  value:
                    errors:
                      - code: invalid
                        detail: iban is invalid
                        source:
                          pointer: /supplier/payment_details/iban
                duplicate_iban:
                  summary: The IBAN already belongs to another supplier
                  value:
                    errors:
                      - code: conflict
                        detail: iban is already linked to another supplier
                        source:
                          pointer: /supplier/iban
                        meta:
                          supplier_id: 018f4e5a-9c1d-7b2e-8a3f-1d2c3b4a5f60
                          supplier_name: ACME SAS
        '500':
          $ref: '#/components/responses/500-Internal-Server-Error'
      security:
        - OAuth:
            - supplier_invoice.write
        - SecretKey: []
components:
  parameters:
    X-Qonto-Staging-Token:
      name: X-Qonto-Staging-Token
      in: header
      description: >-
        Required only for Sandbox API requests; to get one, please sign up to
        the [Developer Portal](https://developers.qonto.com/).
      schema:
        type: string
  schemas:
    SupplierWriteRequest:
      type: object
      required:
        - supplier
      properties:
        supplier:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name of the supplier.
              example: ACME SAS
            currency:
              type: string
              description: Default currency of the supplier, as an ISO 4217 code.
              example: EUR
            default_vat_rate:
              type: number
              description: Default VAT rate applied to the supplier's invoices, in percent.
              example: 20
            tax_identifiers:
              $ref: '#/components/schemas/SupplierTaxIdentifiers'
            address:
              $ref: '#/components/schemas/SupplierAddress'
            contact_info:
              $ref: '#/components/schemas/SupplierContactInfo'
            e_invoicing:
              $ref: '#/components/schemas/SupplierEInvoicing'
            payment_details:
              $ref: '#/components/schemas/SupplierPaymentDetails'
    SupplierResponse:
      type: object
      required:
        - supplier
      properties:
        supplier:
          $ref: '#/components/schemas/Supplier'
    BadRequestResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BadRequestError'
      required:
        - errors
    SupplierTaxIdentifiers:
      type: object
      description: Tax identifiers of the supplier. Omitted from responses when empty.
      properties:
        vat_number:
          type: string
          description: VAT number of the supplier.
          example: FR12345678901
        tin_number:
          type: string
          description: >-
            Tax identification number of the supplier. For French suppliers this
            is a SIREN (9 digits) or a SIRET (14 digits).
          example: '123456789'
    SupplierAddress:
      type: object
      description: Postal address of the supplier. Omitted from responses when empty.
      properties:
        street_address:
          type: string
          example: 1 rue de la Paix
        zip_code:
          type: string
          maxLength: 20
          example: '75002'
        province_code:
          type: string
          example: IDF
        city:
          type: string
          example: Paris
        country_code:
          type: string
          description: >-
            ISO 3166-1 alpha-2 country code. When omitted, it is inferred from
            the VAT number or the IBAN when possible.
          example: FR
    SupplierContactInfo:
      type: object
      description: Contact details of the supplier. Omitted from responses when empty.
      properties:
        email:
          type: string
          format: email
          example: billing@acme.test
        phone_number:
          type: string
          maxLength: 20
          example: '+33102030405'
    SupplierEInvoicing:
      type: object
      description: E-invoicing details of the supplier. Omitted from responses when empty.
      properties:
        recipient_code:
          type: string
          maxLength: 20
          description: >-
            Recipient code (for example the Italian SDI code) used to route
            e-invoices.
          example: ABC1234
    SupplierPaymentDetails:
      type: object
      description: Payment details of the supplier. Omitted from responses when empty.
      properties:
        iban:
          type: string
          description: IBAN of the supplier. Must be a valid IBAN.
          example: FR7630006000011234567890189
    Supplier:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the supplier.
          example: 018f4e5a-9c1d-7b2e-8a3f-1d2c3b4a5f60
        organization_id:
          type: string
          format: uuid
          description: Identifier of the organization the supplier belongs to.
          example: 018f4e5a-1111-7b2e-8a3f-1d2c3b4a5f60
        name:
          type: string
          description: Name of the supplier.
          example: ACME SAS
        status:
          type: string
          description: >-
            Lifecycle status of the supplier. It cannot be changed through the
            create and update endpoints.
          enum:
            - unarchived
            - archived
            - draft
          example: unarchived
        currency:
          type: string
          description: Default currency of the supplier, as an ISO 4217 code.
          example: EUR
        default_vat_rate:
          type: number
          description: Default VAT rate applied to the supplier's invoices, in percent.
          example: 20
        outstanding_balance:
          type: object
          description: >-
            Outstanding balance of the supplier. Only returned to callers with
            access to supplier invoice insights.
          properties:
            value:
              type: string
              example: '22.10'
            currency:
              type: string
              example: EUR
        tax_identifiers:
          $ref: '#/components/schemas/SupplierTaxIdentifiers'
        address:
          $ref: '#/components/schemas/SupplierAddress'
        contact_info:
          $ref: '#/components/schemas/SupplierContactInfo'
        e_invoicing:
          $ref: '#/components/schemas/SupplierEInvoicing'
        payment_details:
          $ref: '#/components/schemas/SupplierPaymentDetails'
        created_at:
          type: string
          format: date-time
          description: Date and time when the supplier was created.
          example: '2026-01-15T09:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Date and time when the supplier was last updated.
          example: '2026-01-16T14:05:00Z'
    UnauthorizedResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/UnauthorizedError'
      required:
        - errors
    ForbiddenResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ForbiddenError'
      required:
        - errors
    ConflictError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Insurance Contract Already Exists:
          code: conflict
          detail: >-
            Insurance contract with id 123 and type business_liability already
            exists
    BadRequestError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
        source:
          type: object
          properties:
            pointer:
              type: string
              description: >-
                The property in the request body that caused the error
                (optional).
            parameter:
              type: string
              description: The query parameter that caused the error (optional).
      required:
        - code
        - detail
      x-examples:
        Authorization field missing:
          code: bad_request
          detail: Authorization field missing
    UnauthorizedError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Invalid credentials:
          code: unauthorized
          detail: Invalid credentials
    ForbiddenError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Insufficient permissions:
          code: forbidden
          detail: User does not have sufficient permissions for this action.
  responses:
    400-Bad-request:
      description: Returns a bad request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestResponseBody'
          examples:
            Authorization field missing:
              value:
                errors:
                  - code: bad_request
                    detail: Authorization field missing
    401-Unauthorized:
      description: Returns an unauthorized error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponseBody'
          examples:
            authorization_header_missing:
              value:
                errors:
                  - code: authorization_header_missing
                    detail: authorization header missing
            authorization_token_invalid:
              value:
                errors:
                  - code: authorization_token_invalid
                    detail: authorization token invalid
    403-Forbidden:
      description: Returns a forbidden error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenResponseBody'
          examples:
            Insufficient permissions:
              value:
                errors:
                  - code: forbidden
                    detail: User does not have sufficient permissions for this action.
    409-Conflict:
      description: Returns a conflict error.
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ConflictError'
    500-Internal-Server-Error:
      description: Returns an internal server error.
  securitySchemes:
    OAuth:
      type: oauth2
      description: >
        Bearer authorization header: `Bearer <token>`, where `<token>` is the
        access token received from the authorization server at the end of the
        [OAuth 2.0
        flow](/get-started/business-api/authentication/oauth/oauth-flow).
      flows:
        authorizationCode:
          refreshUrl: https://oauth.qonto.com/oauth2/token
          authorizationUrl: https://oauth.qonto.com/oauth2/auth
          scopes:
            attachment.read: Retrieve attachments
            attachment.write: Upload attachments and remove attachments from transactions
            bank_account.write: Create, update and close bank accounts
            beneficiary.trust: Trust SEPA beneficiaries
            card.read: Retrieve cards
            card.write: Create or update cards
            cash_flow_category.read: Retrieve cash flow categories
            cash_flow_category.write: >-
              Create, update and delete cash flow categories, and assign them to
              transactions
            client.read: Retrieve clients
            client.write: Create clients
            client_invoice.write: Create client invoices
            client_invoices.read: Retrieve client invoices and credit notes
            einvoicing.read: Retrieve e-invoicing settings
            embed_auth_link.write: Create Embed auth links
            insurance_contract.read: Retrieve insurance contracts
            insurance_contract.write: Create and update insurance contracts
            internal_transfer.write: >-
              Create internal transfers (between 2 Qonto accounts of the same
              organization)
            international_transfer.write: Create international transfers
            membership.read: Retrieve the authentified membership
            membership.write: Invite team members
            offline_access: Retrieve a refresh token
            organization.read: >-
              Retrieve organization, bank accounts, transactions, transfers,
              beneficiaries, labels, memberships, requests & statements
            payment.write: Create external transfers and untrust beneficiaries
            payment_link.read: >-
              Retrieve payment links, their payments, and the available payment
              methods
            payment_link.write: >-
              Connect to the payment links provider, create and deactivate
              payment links
            product.read: Retrieve products
            product.write: Create products
            request_cards.write: Create card requests
            request_review.write: Approve or decline requests
            request_transfers.write: Create transfer requests
            sepa_direct_debit.read: View SEPA Direct Debit payments
            sepa_direct_debit.write: Manage SEPA Direct Debit payments
            subscription.read: Retrieve the organization's current subscription plan
            supplier_invoice.read: Retrieve supplier invoices
            supplier_invoice.write: Create supplier invoices
            team.read: Retrieve teams
            team.write: Create teams
            terminal.read: View your payment terminals
            terminal.write: Configure your terminals and initiate payments
            user_organization.read: View the organizations the user has granted access to
            webhook: >-
              Receive a notification each time a particular event occurs in
              Qonto
          tokenUrl: https://oauth.qonto.com/oauth2/token
    SecretKey:
      type: apiKey
      description: cf. [API key](/get-started/business-api/authentication/api-key)
      name: Authorization
      in: header

````