Tutorial·5 min

Create an organization

Create the Client Account organization that every API Key and request is scoped to. You send a name and an email, and get back the generated organization id.

API reference

Endpoint

POST /organizations

Auth

X-API-Key

Body

{ name, email }

Returns

201 { id }

Before you start

1. A Core API base URL

   Pick the environment you are building against. Base URLs has the details.

   • ProductionProvided at onboardingMutual TLS required
   • Sandboxhttps://staging-api.emergentriskinternational.com/api/v1Same contract as production
   • Localhttp://127.0.0.1:3001/api/v1apps/backend on your machine

2. An API Key

   Organization-scoped, sent in the X-API-Key header and issued by ERI support. See Authentication.

   Running the backend locally

   Bootstrap the first key from apps/backend. The script prints the raw key once, so store it outside the repository.

   pnpm migrations:up
   pnpm api-keys:bootstrap

3. The organization's details

   A name of 2 to 200 characters and a corporate email address. The email must not belong to another organization.

1. 1

   Step 1: Prepare the payload

   Save the organization's details as create-org.json.

   The body is strict: exactly name and email. Any other field fails validation, so there is nothing optional to leave out.

   create-org.json

   {
     "name": "Acme Fintech Corp",
     "email": "operations@acmefintech.example"
   }

2. 2

   Step 2: Send the request

   Export the base URL for your environment and your API Key, then post the payload to /organizations.

   Send Content-Type: application/json with every request. The key goes in X-API-Key, never in the URL.

   Terminal

   export CORE_API_BASE_URL="http://127.0.0.1:3001/api/v1"
   export ERI_API_KEY="<raw API Key from bootstrap or ERI support>"

   cURL

   curl -X POST "$CORE_API_BASE_URL/organizations" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: $ERI_API_KEY" \
     -d @create-org.json

   Python

   import os, requests
   
   response = requests.post(
       f"{os.environ['CORE_API_BASE_URL']}/organizations",
       headers={"X-API-Key": os.environ["ERI_API_KEY"]},
       json={"name": "Acme Fintech Corp", "email": "operations@acmefintech.example"},
   )
   organization_id = response.json()["id"]

   Node.js

   const response = await fetch(`${process.env.CORE_API_BASE_URL}/organizations`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "X-API-Key": process.env.ERI_API_KEY,
     },
     body: JSON.stringify({
       "name": "Acme Fintech Corp",
       "email": "operations@acmefintech.example",
     }),
   });
   const { id } = await response.json();

3. 3

   Step 3: Handle the response

   A successful call returns 201 Created with the generated id and nothing else. No status, contact details or credential links come back, so persist the id now.

   Errors share one JSON envelope with a stable code to branch on. Pick a status to see the exact body.

   201Created

   When

   The organization was created.

   What to do

   Persist the returned id. It is the only field in the response.

   Response body

   {
     "id": "019f1240-0000-7000-8000-000000000001"
   }

4. 4

   Step 4: Read it back

   Confirm the organization with GET /organizations/{id}, using the same key.

   Reads are tenant-scoped

   The Core API derives tenant context from the API Key. Any id outside your Client Account returns 404, whether it exists or not.

   cURL

   curl "$CORE_API_BASE_URL/organizations/019f1240-0000-7000-8000-000000000001" \
     -H "X-API-Key: $ERI_API_KEY"

   Python

   response = requests.get(
       f"{os.environ['CORE_API_BASE_URL']}/organizations/{organization_id}",
       headers={"X-API-Key": os.environ["ERI_API_KEY"]},
   )
   organization = response.json()

   Node.js

   const response = await fetch(`${process.env.CORE_API_BASE_URL}/organizations/${id}`, {
     headers: { "X-API-Key": process.env.ERI_API_KEY },
   });
   const organization = await response.json();

   200 OK

   {
     "id": "019f1240-0000-7000-8000-000000000001",
     "name": "Acme Fintech Corp",
     "email": "operations@acmefintech.example"
   }

You have a Client Account

Every API key and request from here on is scoped to the organization you just created.

• Ingest the report feed→Page through the intelligence your Client Account has access to, newest first.GET /reports
• Search the archive→Find reports by what they say instead of paging the whole feed.GET /reports/search
• Retrieve an organization→Full reference for the read call, including every error response.GET /organizations/{id}