Organization API

https://api.gandi.net/v5/organization

Gandi Organization API

Introduction

This section of our documentation explains how to view information on organizations at Gandi.net through our REST API. Organizations are used to share products via user accounts.

The Organization API is a read-only API. All organization management must be performed via our web interface:
https://admin.gandi.net/organizations/

General information on using organizations at Gandi can be found in our public documentation at:
https://docs.gandi.net/en/sharing_products/index.html

Organization Management

https://api.gandi.net/v5/organization/organizations

get List organizations

This route returns a list of organizations the authenticated user has permission to access.

Request

Query String
  • Optional
    • ~namestring
      Filters the list by a name pattern.
      Example: *lice
      Example: alic*
    • namestring
      Filters the list by exact name.
    • permissionstring
      Filters the list by the permission the authenticated user has on that organization and products in it.
    • sort_bystring

      One of: "name", "type", "id"

      Default: "name"

      Used to specify how you want the results sorted.
    • typestring

      One of: "individual", "company", "association", "publicbody"

      Filters the list by type of organization.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • idstring
        The main identifier of the organization. Also known as sharing_id in many routes.
      • namestring
        Unique name of the organization.
      Optional
      • corporateboolean
        Flag to indicate the corporate status for the organization.
      • emailstring
        The email address of the organization.
      • firstnamestring
        The first name of the organization.
      • lastnamestring
        The last name of the organization.
      • orgnamestring
        The company, association, or public body name of the (non-individual) organization.
      • resellerboolean
        Flag to indicate the reseller status for the organization.
      • sirenstring
        The siren number of the (non-individual) organization.
      • typestring
        The type of the organization.
      • vat_numberstring
        The VAT number of the (non-individual) organization.
    Example:
    [
      {
        "name": "alice",
        "firstname": "Alice",
        "lastname": "Doe",
        "id": "80548b45-e18d-4cab-adef-e10a8406de4a",
        "reseller": false,
        "corporate": true,
        "type": "individual",
        "email": "alice@example.net"
      },
      {
        "name": "bob",
        "firstname": "Bob",
        "orgname": "Bob's Roads",
        "lastname": "Doe",
        "email": "bob@example.net",
        "reseller": false,
        "corporate": false,
        "type": "publicbody",
        "id": "e1ab1204-e638-4fd8-85a4-34dd95013cdc"
      },
      {
        "name": "ron",
        "firstname": "Ron",
        "orgname": "Ron Inc.",
        "lastname": "Doe",
        "email": "ron@example.net",
        "reseller": false,
        "corporate": false,
        "type": "company",
        "id": "b018061c-a4e3-4d6d-8445-e3837bd23815"
      }
    ]

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create an organization

This route is used to create an organization such as company, association, or public body.

Request

Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • citystring
      the city name of the address.
    • emailstring
      The email address of the organization.
    • firstnamestring
      The first name of the organization.
    • lastnamestring
      The last name of the organization.
    • namestring
      Unique name of the organization.
    • orgnamestring
      The company, association, or public body name of the organization.
    • phonestring
      phone number.
    • streetaddrstring
      the street address of the organization.
    • typestring

      One of: "company", "association", "publicbody"

      The type of the organization.
    Optional
    • countrystring
      country ISO code of the address.
    • faxstring
      fax number.
    • langstring
      language of the organization for emails.
    • referencestring
      Optional text to display on the invoice, such as your own reference info.
    • resellerboolean
      Flag to set the organization as reseller.
    • sirenstring
      The siren number of the organization.
    • statestring
      state ISO code of the address.
    • streetaddr2string
      additional street address info of the organization.
    • vat_numberstring
      The VAT number of the organization.
    • zipstring
      zip code of the address.
    Example:
    {
      "type": "company",
      "name": "Poppy Red LLC",
      "firstname": "John",
      "lastname": "Do",
      "orgname": "Poppy Red LLC",
      "email": "jd@example.net",
      "streetaddr": "42 Rue du Soleil Levant",
      "zip": "17000",
      "city": "La Rochelle",
      "country": "FR",
      "state": "FR-NAQ",
      "phone": "+33.612345678",
      "reseller": false
    }

Responses

201

The resource has been created.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • idstring
      Created Organization ID.
    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

/v5/organization/organizations/{org_id}

https://api.gandi.net/v5/organization/organizations/{org_id}

get Show organization information

This route returns the information of the organization with the given ID.

Request

URI Parameters
    • org_idstring
      Organization ID.

Responses

200

Body
  • application/json
    object

    With the following properties:

    • citystring
      the city name of the address.
    • countrystring
      country ISO code of the address.
    • emailstring
      the email address of the user.
    • firstnamestring
      the first name of the user.
    • idstring
      the sharing id of the user.
    • lastnamestring
      the last name of the user.
    • namestring
      the sharing name of the user.
    • resellerboolean
      Flag set for reseller organization
    • streetaddrstring
      the street address of the user.
    • zipstring
      zip code of the address.
    Optional
    • faxstring
      fax number.
    • langstring
      language used by the user.
    • phonestring
      phone number.
    • referencestring
      Optional text to display on the invoice, such as your own reference info.
    • statestring
      state ISO code of the address.
    • streetaddr2string
      additional street address info of the user.

patch Update an organization

This route updates the information of the organization of the given ID.

Request

URI Parameters
    • org_idstring
      Organization ID.
Body
  • application/json
    object

    With the following properties:

    Optional
    • citystring
      the city name of the address.
    • countrystring
      country (ISO 3166-1 alpha-2) code of the address.
    • emailstring
      The email address of the organization.
    • faxstring
      fax number.
    • firstnamestring
      The first name of the organization.
    • langstring

      One of: "en", "es", "fr", "ja", "zh-hans", "zh-hant"

      language code of the organization for emails.
    • lastnamestring
      The last name of the organization.
    • namestring
      Unique name of the organization.
    • phonestring
      phone number.
    • referencestring
      Optional text to display on the invoice, such as your own reference info.
    • resellerboolean
      Set the organization as reseller if true, cannot be set to false.
    • sirenstring
      The siren number of the organization.
    • statestring
      Country subdivisions(ISO 3166-2) of the address.
    • streetaddrstring
      the street address of the organization.
    • streetaddr2string
      additional street address info of the organization.
    • vat_numberstring
      The VAT number of the organization.
    • zipstring
      zip (postal) code of the address.

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

delete Delete an organization

This route deletes an organization if possible. If an organization owns a product or has money on its prepaid account, it cannot be deleted.

Request

URI Parameters
    • org_idstring
      Organization ID.

Responses

204

The request has succeeded but does not need to return a response.

409

The request could not be completed due to a conflict with the current state of the target resource.
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Explanation message.

Management Of Customers Under a Reseller Organization

https://api.gandi.net/v5/organization/organizations/{org_id}/customers

When an organization is flagged reseller, then the product is not legally owned by the organization, but by the organization's customers.

get List customers

This route returns the list of customers of the given reseller organization.

Request

URI Parameters
    • org_idstring
      Organization ID.
Query String
  • Optional
    • namestring
      Filters the list by name, with optional patterns.
      Example: *lice
      Example: alic*
    • pageinteger

      Default: 1

      Minimum: 1

      Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
    • per_pageinteger

      Minimum: 1

      How many items to display per page.
    • permissionstring
      Filters the list by the permission the authenticated user has on that organization and products in it.
    • sort_bystring

      One of: "name", "type", "id"

      Default: "name"

      Used to specify how you want the results sorted.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Headers
    • Total-Countinteger
      Total number of items.
    Optional
    • Linkstring
      Links to next and last page.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • emailstring
        Email of the customer.
      • firstnamestring
        First name of the customer.
      • idstring
        The main identifier of the customer. Also known as sharing_id in many routes.
      • lastnamestring
        Last name of the customer.
      • namestring
        Name of the customer.
      • typestring

        One of: "individual", "company", "association", "publicbody"

        Type of the customer organization.
      Optional
      • orgnamestring
        Organization legal name of the customer.
    Example:
    [
      {
        "id": "80548b45-e18d-4cab-adef-e10a8406de4a",
        "name": "alice",
        "firstname": "Alice",
        "lastname": "Doe",
        "type": "individual",
        "email": "alice@example.net"
      },
      {
        "id": "e1ab1204-e638-4fd8-85a4-34dd95013cdc",
        "name": "bob",
        "firstname": "Bob",
        "lastname": "Doe",
        "type": "publicbody",
        "orgname": "Bob's Roads",
        "email": "bob@example.net"
      },
      {
        "id": "b018061c-a4e3-4d6d-8445-e3837bd23815",
        "name": "ron",
        "firstname": "Ron",
        "lastname": "Doe",
        "type": "company",
        "orgname": "Ron Inc.",
        "email": "ron@example.net"
      }
    ]

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create a new customer

This route is used to create a new customer.

Request

URI Parameters
    • org_idstring
      Organization ID.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • citystring
    • countrystring
      Country code.
    • emailstring
    • firstnamestring
      First name.
    • lastnamestring
      Last name.
    • phonestring
    • streetaddrstring
      Street address.
    • typestring

      One of: "individual", "company", "association", "publicbody"

      Type of the customer organization.
    Optional
    • faxstring
    • orgnamestring
      Organization legal name.
    • referencestring
      Optional text to display on the invoice, such as your own customer reference info.
    • statestring
      State/Province/Region.
    • streetaddr2string
      Apt. number, suite, building, etc.
    • zipstring
    Example:
    {
      "type": "company",
      "firstname": "John",
      "lastname": "Do",
      "orgname": "R&D",
      "email": "jd@example.net",
      "streetaddr": "21 jump street",
      "streetaddr2": "Appt31",
      "zip": "17137",
      "city": "Nieul-sur-mer",
      "country": "FR",
      "state": "FR-NAQ",
      "phone": "+33.612345678",
      "fax": "+33.612345699",
      "reference": "abc/3458"
    }

Responses

201

The resource has been created.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • idstring
      Created customer ID.
    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Management Of A Customer Under a Reseller Organization

https://api.gandi.net/v5/organization/organizations/{org_id}/customers/{id}

get Show customer's information

Request

URI Parameters
    • org_idstring
      Organization ID.
    • idstring
      Customer ID.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • citystring
      the city name of the address.
    • countrystring
      country ISO code of the address.
    • emailstring
      Email of the customer.
    • firstnamestring
      First name of the customer.
    • idstring
      The main identifier of the customer. Also known as sharing_id in many routes.
    • lastnamestring
      Last name of the customer.
    • namestring
      Name of the customer.
    • streetaddrstring
      the street address of the user.
    • typestring

      One of: "individual", "company", "association", "publicbody"

      Type of the customer organization.
    Optional
    • faxstring
      fax number.
    • orgnamestring
      Organization legal name of the customer.
    • phonestring
      phone number.
    • referencestring
      Optional text to display on the invoice, such as your own customer reference info.
    • statestring
      state ISO code of the address.
    • streetaddr2string
      additional street address info of the user.
    • zipstring
      zip code of the address.
    Example:
    {
      "id": "80548b45-e18d-4cab-adef-e10a8406de4a",
      "name": "alice",
      "firstname": "Alice",
      "lastname": "Doe",
      "type": "individual",
      "email": "alice@example.net",
      "streetaddr": "5000 Fraise",
      "zip": "17540",
      "city": "Les Rivieres d'Anais",
      "country": "FR"
    }

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

patch Update customer's information

Request

URI Parameters
    • org_idstring
      Organization ID.
    • idstring
      Customer ID.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Optional
    • citystring
      the city name of the address.
    • countrystring
      country (ISO 3166-1 alpha-2) code of the address.
    • emailstring
      The email address of the customer.
    • faxstring
      fax number.
    • firstnamestring
      The first name of the customer; clients with type 'individual' cannot update their firstname.
    • langstring

      One of: "en", "es", "fr", "ja", "zh-hans", "zh-hant"

      language code of the organization for emails.
    • lastnamestring
      The last name of the customer; clients with type 'individual' cannot update their lastname.
    • phonestring
      phone number of the customer.
    • referencestring
      reference field written on every invoice.
    • sirenstring
      The siren number of the organization.
    • statestring
      Country subdivisions (ISO 3166-2) of the address.
    • streetaddrstring
      the street address of the customer.
    • streetaddr2string
      additional street address info of the customer.
    • sync_contact_emailstring

      One of: "never", "match", "always"

      If the customer owns domains, the update of the email can automatically propagate the update of the email of the owners of domains. By default, the change is not propagated. If 'match' is chosen, the domains' owners that have the same email are updated, if 'always' is chosen, then the email is always updated.
    • vat_numberstring
      The VAT number of the organization.
    • zipstring
      zip (postal) code of the address.
    Example:
    Update email with domain owners email
    {
      "email": "hello@example.net",
      "sync_contact_email": "match"
    }
    Example:
    Update the reference of the customer
    {
      "reference": "POPPYRED500"
    }

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

delete Delete customer

This route deletes a customer if possible. If an customer owns a product, it cannot be deleted.

Request

URI Parameters
    • org_idstring
      Organization ID.
    • idstring
      Customer ID.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

204

The request has succeeded but does not need to return a response.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

409

The request could not be completed due to a conflict with the current state of the target resource.
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Explanation message.

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Authenticated User Information

https://api.gandi.net/v5/organization/user-info

get Get user information

This route returns information on the current authenticated user.

Request

Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • citystring
      the city name of the address.
    • emailstring
      the email address of the user.
    • idstring
      the sharing id of the user.
    • langstring
      language used by the user.
    • namestring
      the sharing name of the user.
    • usernamestring
      the username of the user.
    Optional
    • countrystring
      country ISO code of the address.
    • faxstring
      fax number.
    • firstnamestring
      the first name of the user.
    • lastnamestring
      the last name of the user.
    • phonestring
      phone number.
    • statestring
      state ISO code of the address.
    • streetaddrstring
      the street address of the user.
    • streetaddr2string
      additional street address info of the user.
    • zipstring
      zip code of the address.
    Example:
    {
      "id": "ebfcd3cd-e014-4a3d-8216-6e342f227c3d",
      "username": "alice",
      "email": "alice@example.org",
      "name": "alice",
      "firstname": "Alice",
      "lastname": "Doe",
      "streetaddr": "5 rue neuve",
      "zip": "75001",
      "city": "Paris",
      "state": "FR-IDF",
      "country": "FR",
      "phone": "+33.123456789",
      "lang": "en"
    }

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key