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

# Create an organization

> Creates an external organization.



## OpenAPI

````yaml /api-reference/openapi.yaml post /organizations
openapi: 3.0.1
info:
  title: Nocotax API
  version: v1
servers:
  - url: https://api.nocotax.app/
    variables:
      protocol:
        default: https
      defaultHost:
        default: api.nocotax.app/
security:
  - basic_auth: []
tags:
  - name: Introduction
    x-traitTag: true
    description: >
      The Nocotax API is organized around REST. Our API is designed to have 

      predictable, resource-oriented URLs and to use HTTP response codes to 

      indicate API errors. We use built-in HTTP features, like HTTP verbs, 

      which can be understood by off-the-shelf HTTP clients.


      JSON will be returned in all responses from the API, including errors.


      To make the Nocotax API as secure as possible. Authentication is
      performed 

      through HTTP Basic Auth. Credentials can be found on your Nocotax 

      developers menu, in the "API Keys" section.
  - name: Authentication
    x-traitTag: true
    description: >
      Authentication to the API occurs via HTTP Basic Auth.

      Provide your Account ID as the basic auth username, and the API secret key
      as the password.


      All API requests must be made over HTTPS. Calls made over plain HTTP will
      fail.

      You must authenticate for all requests.


      You can manage your API keys from your account.

      Your API keys carry many privileges, so be sure to keep them secret!
  - name: Errors
    x-traitTag: true
    description: >
      Nocotax uses conventional HTTP response codes to indicate success or
      failure of an API request.


      In general, codes in the 2xx range indicate success,

      codes in the 4xx range indicate an error that resulted from the provided
      information

      (e.g. a required parameter was missing), and codes in the 5xx range
      indicate an error with our servers.


      ```
        HTTP status codes summary
        
        200 OK - Everything worked as expected.
        201 Created - Resource has been successfully created
        202 Accepted - Request has been accepted, but requires asynchronous work to be fully performed

        400 Bad Request - Request failed due to a combination of errors
        401 Unauthorized - No valid API credentials provided.
        402 Payment Required - Your request was in livemode while your account is not activated for live requests yet.
        403 Forbidden - You are not authorized to access the requested item.
        404 Not Found - The requested item doesn't exist.
        406 Unacceptable - Your request format was not supported. Use JSON.
        409 Conflict - The data you submitted is in conflict with existing data.
        422 Unprocessable Entity - Often missing a required parameter.
        429 Too Many Requests - You sent us too many API requests in a row. Please retry later.
        
        500, 502, 503, 504 Server errors - something went wrong on our end.
      ```
  - name: Pagination
    x-traitTag: true
    description: >
      All top-level API resources have support for bulk fetches “list” API
      methods.

      For instance, you can list organization, list invoices.


      We use cursor-based pagination using the parameter `after`.

      Pass `after` parameter at the previous page last object id value to
      determine where to start in the list.


      Reverse pagination is possible as well thanks to the `before` parameter.


      ## Attributes

      <table>
        <tr><th>Attribute</th><th>Type</th></tr>
        <tr><td><strong>limit</strong></td><td>integer, optional A limit on the number of objects to be returned. Must be included between 1 and 100</td>
        <tr><td><strong>after</strong></td><td>string, optional A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `after=obj_foo` in order to fetch the next page of the list.</td>
        <tr><td><strong>before</strong></td><td>string, optional A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `before=obj_bar` in order to fetch the previous page of the list.</td>
      </table>


      ### List Response format

      <table>
        <tr><th>Attribute</th><th>Type</th></tr>
        <tr><td><strong>object</strong></td><td>string, value is `list`</td></tr>
        <tr><td><strong>data</strong></td><td>array, An array containing the actual response elements, paginated by any request parameters.</td></tr>
        <tr><td><strong>has_before</strong></td><td>boolean, Whether or not there are more elements available before this page. If `false`, this page is the beginning of the list.</td></tr>
        <tr><td><strong>has_more</strong></td><td>boolean, Whether or not there are more elements available after this page. If `false`, this page is the end of the list</td></tr>
      </table>
paths:
  /organizations:
    post:
      tags:
        - Organizations
      summary: Create an organization
      description: Creates an external organization.
      operationId: OrganizationCreate
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                billing_address:
                  type: object
                  properties:
                    recipient:
                      type: string
                      nullable: true
                    line1:
                      type: string
                      nullable: true
                    line2:
                      type: string
                      nullable: true
                    city:
                      type: string
                      nullable: true
                    postal_code:
                      type: string
                      nullable: true
                    state:
                      type: string
                      nullable: true
                    country:
                      type: string
                      description: >-
                        Two-letter country code that represents the country of
                        this organization's billing address
                  required:
                    - country
                business_registration_number:
                  type: string
                  nullable: true
                contact_information:
                  type: object
                  nullable: true
                  properties:
                    email:
                      type: string
                      format: email
                      nullable: true
                is_professional:
                  type: boolean
                name:
                  type: string
                roles:
                  type: array
                  description: >-
                    A set of capabilities defining how the organization
                    interacts with the Account. Set to `BUYER` this entity
                    purchases products or services from your platform. Set to
                    `MERCHANT` if it represents a supplier, or a platform 3rd
                    party agent, selling to customers.
                  items:
                    type: string
                    enum:
                      - BUYER
                      - MERCHANT
                tax_identification_number:
                  type: string
                  nullable: true
                tax_registration_data:
                  type: object
                  properties:
                    country:
                      type: string
                    type:
                      type: string
                      enum:
                        - standard
                    number:
                      type: string
                  required:
                    - country
                    - type
                    - number
                timezone:
                  type: string
                  nullable: true
              required:
                - billing_address
                - name
                - roles
      responses:
        '201':
          description: successful
          content:
            application/json:
              example:
                id: org_17920607733q8i4fb27ab7
                livemode: false
                object: organization
                billing_address:
                  line1: 3521 Sawayn Street
                  line2: Suite 173
                  city: Port Tarafort
                  postal_code: '78554'
                  country: PF
                business_registration_number: '03801589700309'
                contact_information: {}
                is_professional: true
                name: Ryan and Sons
                ownership: external
                roles:
                  - BUYER
                timezone: Etc/UTC
                tax_identification_number: '177266129'
                created_at: '2026-10-15T10:39:33.176Z'
                updated_at: '2026-10-15T10:39:33.176Z'
              schema:
                $ref: '#/components/schemas/organization'
        default:
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    organization:
      type: object
      properties:
        id:
          type: string
        livemode:
          type: boolean
        object:
          type: string
        billing_address:
          type: object
          properties:
            recipient:
              type: string
              nullable: true
            line1:
              type: string
              nullable: true
            line2:
              type: string
              nullable: true
            city:
              type: string
              nullable: true
            postal_code:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            country:
              type: string
        business_registration_number:
          type: string
          nullable: true
        contact_information:
          type: object
          nullable: true
          properties:
            email:
              type: string
              format: email
              nullable: true
        is_professional:
          type: boolean
        name:
          type: string
        ownership:
          type: string
          description: >-
            Whether the organization is a business entity belonging to the
            account owner, or a 3rd party, doing business with the account
            entities (supplier, 3rd party merchant or customer)

            `self`: This organization corresponds to a business entity belonging
            to the current account's owner. For instance, its company or a
            subsidiary.

            `external`: This organization corresponds to a business entity
            having business with the current account's owner. It could be given
            roles such as `MERCHANT` or `BUYER`. See `roles` for more details.
          enum:
            - self
            - external
        roles:
          type: array
          description: >-
            Only valid when `ownership=external`. A set of capabilities defining
            how the organization interacts with the Account. Set to `BUYER` if
            you sell products or services to this entity. Set to `MERCHANT` if
            it represents a supplier, or a platform 3rd party agent, selling to
            customers.
          items:
            type: string
            enum:
              - BUYER
              - MERCHANT
          nullable: true
        timezone:
          type: string
        tax_identification_number:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    errorResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
        type:
          type: string
          enum:
            - INVALID_REQUEST_ERROR
        params:
          nullable: true
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              errors:
                type: array
                items:
                  type: string
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.