# Organizations

Organizations and their settings

Base URL: `https://api.cv-transformer.com/v1`. Endpoints: `GET /organizations`, `PATCH /organizations`. Authenticate with the header `Authorization: Bearer YOUR_API_KEY` (see [authentication](https://www.cv-transformer.com/nb-NO/api-reference/authentication.md)).

## The organization object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. Read-only. |
| `billing_account_id` | `uuid` | Identifier of the billing account this organization belongs to. Read-only. References [`billing_accounts.id`](https://www.cv-transformer.com/nb-NO/api-reference/billing_accounts.md). |
| `bullhorn_corporation_id` | `text \| null` | Identifier of the organization's corporation in Bullhorn. Read-only. |
| `bullhorn_private_label_id` | `integer \| null` | Identifier of the organization's private label in Bullhorn, used to match Bullhorn users to the organization. Read-only. |
| `default_layout_id` | `uuid \| null` | Identifier of the layout new candidates use by default. References [`layouts.id`](https://www.cv-transformer.com/nb-NO/api-reference/layouts.md). |
| `created_at` | `timestamp with time zone` | Creation timestamp. Read-only. |
| `updated_at` | `timestamp with time zone` | Last modification timestamp. |
| `deleted_at` | `timestamp with time zone \| null` | Deletion timestamp. Read-only. |
| `active_ats_integration` | `IntegrationName \| null` | ATS integration that is currently active. |
| `allow_inspection` | `boolean` | Whether the CV-Transformer team is allowed to inspect the organization to debug errors. |
| `allow_word_output` | `boolean` | Whether Word output is enabled for the organization. |
| `allowed_senders` | `text[]` | Email addresses allowed to send CVs to the organization's inbox. Can be partial, like `*@example.com`. |
| `ats` | `text` | The ATS this organization uses. |
| `avatar` | `text \| null` | Avatar image of the organization. |
| `carerix_attachment_node_type` | `text \| null` | Identifier of the Carerix attachment type that exported files get. |
| `carerix_entity_kind` | `"CREmployee" \| "CRMatch"` | Carerix entity that candidates are linked to: a candidate (`CREmployee`) or a match (`CRMatch`). |
| `default_prompt` | `text` | Default prompt for filling in candidates. |
| `delete_candidates_after` | `integer \| null` | Number of days after which candidates are deleted automatically. |
| `detect_candidate_language_from_attachment` | `boolean` | Whether a candidate's language is detected from its first uploaded attachment. |
| `enable_beta_integrations` | `boolean` | Whether integrations in beta are available to the organization. Read-only. |
| `enable_data_tab` | `boolean` | Read-only. |
| `external_variables` | `Array<LayoutVariable>` | Variables of the data imported from the external integration. |
| `fts` | `tsvector` | Full text search index. Read-only. |
| `member_variables` | `Array<MemberVariable>` | Variables defined on each member, usable in layouts. |
| `model` | `text` | AI model the organization uses. |
| `name` | `text` | Name of the organization. |
| `proposal_by` | `ProposalAuthor` | Author shown on web proposals. |
| `proposal_reactions` | `Array<ProposalReaction>` | Reactions allowed on proposals. |
| `require_mfa` | `boolean` | Whether MFA is required for members to access this organization. Read-only. |
| `salesforce_instance_url` | `text \| null` | URL of the organization's Salesforce instance. Read-only. |
| `seven20_export_make_primary_cv_when_empty` | `boolean` | Whether an export to Seven20 makes the CV primary when the candidate has no primary CV. |
| `slug` | `text` | Unique string. The organization's candidate inbox is `{{slug}}@candidates.cv-transformer.com`. |
| `status` | `OrganizationStatus` | Internal status of the organization. Read-only. |
| `type` | `OrganizationType \| null` | Type of the organization. Read-only. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "billing_account_id": "00000000-0000-0000-0000-000000000000",
  "bullhorn_corporation_id": "12345",
  "bullhorn_private_label_id": 0,
  "default_layout_id": "00000000-0000-0000-0000-000000000000",
  "mercury_tenant_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-01T12:00:00+00:00",
  "updated_at": "2026-01-01T12:00:00+00:00",
  "deleted_at": null,
  "active_ats_integration": "GreenhouseV3",
  "allow_inspection": false,
  "allow_word_output": false,
  "allowed_senders": [],
  "ats": "",
  "avatar": "",
  "carerix_attachment_node_type": "",
  "carerix_entity_kind": "CREmployee",
  "default_prompt": "",
  "delete_candidates_after": 0,
  "detect_candidate_language_from_attachment": false,
  "enable_beta_integrations": false,
  "external_variables": [
    {
      "ai_instructions": "",
      "sensitive": false,
      "default": "",
      "key": "name",
      "max_length": null,
      "min_length": 0,
      "type": "inline-text"
    },
    {
      "ai_instructions": "",
      "sensitive": false,
      "default": "",
      "key": "description",
      "max_length": null,
      "min_length": 0,
      "type": "text-block"
    }
  ],
  "fts": "'doe':2 'john':1",
  "member_variables": [
    {
      "ai_instructions": "",
      "sensitive": false,
      "default": "",
      "key": "name",
      "max_length": null,
      "min_length": 0,
      "type": "inline-text"
    },
    {
      "ai_instructions": "",
      "sensitive": false,
      "default": "",
      "key": "description",
      "max_length": null,
      "min_length": 0,
      "type": "text-block"
    }
  ],
  "mercury_region": "UK",
  "model": "",
  "name": "",
  "proposal_by": "contact",
  "proposal_reactions": [
    {
      "id": "invite",
      "body": "",
      "type": "email",
      "subject": ""
    },
    {
      "id": "comment",
      "body": "",
      "type": "email",
      "subject": ""
    },
    {
      "id": "reject",
      "body": "",
      "type": "email",
      "subject": ""
    }
  ],
  "require_mfa": false,
  "salesforce_instance_url": "",
  "seven20_export_make_primary_cv_when_empty": false,
  "slug": "",
  "status": "active",
  "type": "regular"
}
```

### Types

```typescript
type OrganizationType = "ats" | "regular" | "test";

type OrganizationStatus = "active" | "inactive";

type ProposalReaction = ProposalEmailReaction | ProposalLinkReaction;

type ProposalEmailReaction = {
  body: string;
  id: string;
  subject: string;
  type: "email";
};

type ProposalLinkReaction = {
  id: string;
  type: "link";
  url: string;
};

type ProposalAuthor = "contact" | "organization";

type MemberVariable = 
  | LayoutInlineTextVariable
  | LayoutNumberVariable
  | LayoutTextBlockVariable;

type LayoutInlineTextVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: string;
  max_length: number | null;
  min_length: number;
  type: "inline-text";
};

type LayoutNumberVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: number | null;
  max: number | null;
  min: number | null;
  type: "number";
};

type LayoutTextBlockVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: string;
  max_length: number | null;
  min_length: number;
  type: "text-block";
};

type LayoutVariable = 
  | LayoutDateRangeVariable
  | LayoutDateVariable
  | LayoutEnumVariable
  | LayoutImageVariable
  | LayoutInlineTextVariable
  | LayoutJsonVariable
  | LayoutListVariable
  | LayoutNumberVariable
  | LayoutObjectVariable
  | LayoutRatingVariable
  | LayoutTextBlockVariable;

type LayoutDateRangeVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: {
    end: string;
    start: string;
  };
  precision: "year" | "month" | "day";
  type: "date-range";
};

type LayoutDateVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: string;
  precision: "year" | "month" | "day";
  type: "date";
};

type LayoutEnumVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: string;
  options: Array<MultiLanguageString>;
  type: "enum";
};

type LayoutImageVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  type: "image";
};

type LayoutJsonVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: Json;
  type: "json";
};

type LayoutListVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default?: string | null;
  items: Array<LayoutVariable>;
  max_length: number | null;
  min_length: number;
  type: "list";
};

type LayoutObjectVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  fields: Array<LayoutVariable>;
  type: "object";
};

type LayoutRatingVariable = {
  ai_instructions: false | string;
  key: string;
  sensitive: boolean;
  static?: true;
  default: number;
  type: "rating";
};

type Json = 
  | string
  | number
  | boolean
  | null
  | Array<Json>
  | Record<string, Json>;

type MultiLanguageString = {
  default: string;
  [x: string]: string;
};

type IntegrationName = 
  | "Bullhorn"
  | "Carerix"
  | "GreenhouseV3"
  | "JobAdder"
  | "Mercury"
  | "MySolution"
  | "Salesforce"
  | "Seven20"
  | "Tigris";
```

### Related resources

Embed related resources with the [`select` parameter](https://www.cv-transformer.com/nb-NO/api-reference/selecting.md), for example `select=*,billing_accounts!billing_account_id(*)`. Resources related through more than one column need the column as a hint, like `table!column(*)`.

| Embed | Type | Description |
| --- | --- | --- |
| `billing_accounts!billing_account_id(*)` | `object \| null` | The [billing account](https://www.cv-transformer.com/nb-NO/api-reference/billing_accounts.md) referenced by `billing_account_id`. |
| `layouts!default_layout_id(*)` | `object \| null` | The [layout](https://www.cv-transformer.com/nb-NO/api-reference/layouts.md) referenced by `default_layout_id`. |
| `candidate_analytics(*)` | `array` | The [candidate analytics](https://www.cv-transformer.com/nb-NO/api-reference/candidate_analytics.md) referencing this organization through `candidate_analytics.organization_id`. |
| `candidates!organization_id(*)` | `array` | The [candidates](https://www.cv-transformer.com/nb-NO/api-reference/candidates.md) referencing this organization through `candidates.organization_id`. |
| `credit_mutations(*)` | `array` | The [credit mutations](https://www.cv-transformer.com/nb-NO/api-reference/credit_mutations.md) referencing this organization through `credit_mutations.organization_id`. |
| `layouts!organization_id(*)` | `array` | The [layouts](https://www.cv-transformer.com/nb-NO/api-reference/layouts.md) referencing this organization through `layouts.organization_id`. |
| `members!organization_id(*)` | `array` | The [members](https://www.cv-transformer.com/nb-NO/api-reference/members.md) referencing this organization through `members.organization_id`. |
| `webhooks(*)` | `array` | The [webhooks](https://www.cv-transformer.com/nb-NO/api-reference/webhooks.md) referencing this organization through `webhooks.organization_id`. |

## List organizations

`GET /v1/organizations` · requires the `organization:read` scope

Filter on any attribute with `column=operator.value` (see [filtering](https://www.cv-transformer.com/nb-NO/api-reference/filtering.md)). Choose columns and embed related resources with `select` (see [selecting](https://www.cv-transformer.com/nb-NO/api-reference/selecting.md)), and sort and paginate with `order`, `limit` and `offset` (see [sorting and pagination](https://www.cv-transformer.com/nb-NO/api-reference/sorting-pagination.md)).

```bash
curl "https://api.cv-transformer.com/v1/organizations?limit=10&select=*" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: A list of organizations with the selected columns. The `Content-Range` header holds the range returned and the total count, like `0-9/42`.
- `206`: Partial Content
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

## Update organizations

`PATCH /v1/organizations` · requires the `organization:write` scope

Filter on any attribute with `column=operator.value` (see [filtering](https://www.cv-transformer.com/nb-NO/api-reference/filtering.md)). Without filters, this request updates all organizations the API key has access to. Always filter on at least one column, like `id=eq.{id}`. The body holds the attributes to change.

```bash
curl -X PATCH "https://api.cv-transformer.com/v1/organizations?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allow_inspection": false }'
```

Responses:

- `204`: Updated. With the header `Prefer: return=representation`, the response is a `200` whose body holds the updated organizations with the selected columns.
- `400`: The request is malformed, for example an unknown column, an invalid filter or an invalid body.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs, or no permission for this change, for example when writing rows of another organization.
- `409`: The change conflicts with existing data, for example a duplicate key or a reference to a row that does not exist.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

Errors have a JSON body with a `message`, `details` and `hint`, and for database errors a `code`. See the [introduction](https://www.cv-transformer.com/nb-NO/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.cv-transformer.com/v1/openapi.json.