API REFERENCE

Add Organization Domain

On this page

POST/api/organizations/domains

Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/organizations/domains' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "organizationId": "YOUR_ID",
  "domain": "seekermusic.com"
}'

Request body required

Domain-organization mapping parameters

application/json

organizationIdstringrequired

The account ID of the organization

format: uuid

domainstringrequired

The email domain to map (lowercase, no @)

Responses

200Domain mapped to organization successfully (or already mapped)

application/json

statusstring · enumrequired

Status of the request

Values: "success"

idstringrequired

UUID of the domain mapping record

format: uuid

domainstringrequired

The mapped email domain

organization_idstringrequired

The account ID of the organization

format: uuid

400Bad request - invalid or missing parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid authentication

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

403Forbidden - caller is not a member of the organization

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

409Conflict - domain is already mapped to a different organization

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "description": "Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization.  This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Domain-organization mapping parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddOrganizationDomainRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Domain mapped to organization successfully (or already mapped)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AddOrganizationDomainResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid or missing parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - caller is not a member of the organization",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    },
    "409": {
      "description": "Conflict - domain is already mapped to a different organization",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    }
  }
}