curl --request POST \
--url https://agenticadvertising.org/api/organizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organization_name": "Acme Media",
"is_personal": false,
"marketing_opt_in": false
}
'import requests
url = "https://agenticadvertising.org/api/organizations"
payload = {
"organization_name": "Acme Media",
"is_personal": False,
"marketing_opt_in": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({organization_name: 'Acme Media', is_personal: false, marketing_opt_in: false})
};
fetch('https://agenticadvertising.org/api/organizations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agenticadvertising.org/api/organizations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'organization_name' => 'Acme Media',
'is_personal' => false,
'marketing_opt_in' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agenticadvertising.org/api/organizations"
payload := strings.NewReader("{\n \"organization_name\": \"Acme Media\",\n \"is_personal\": false,\n \"marketing_opt_in\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agenticadvertising.org/api/organizations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"organization_name\": \"Acme Media\",\n \"is_personal\": false,\n \"marketing_opt_in\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agenticadvertising.org/api/organizations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"organization_name\": \"Acme Media\",\n \"is_personal\": false,\n \"marketing_opt_in\": false\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"organization": {
"id": "org_01HXZAB123",
"name": "Acme Media"
},
"id": "<string>",
"name": "<string>",
"adopted": true
}{
"success": true,
"organization": {
"id": "org_01HXZAB123",
"name": "Acme Media"
},
"id": "<string>",
"name": "<string>",
"adopted": true
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Create or adopt my organization
Bootstrap the caller’s organization explicitly. Use this when the caller wants to control the organization name, company_type, revenue_tier, or is_personal flag before any agents are registered.
Most storefront-style integrations don’t need this call — POST /api/me/agents will auto-create an org for a fresh OAuth user (corporate or personal workspace based on the email domain) and surface org_auto_created: true in the response. Reach for POST /api/organizations only when the auto-derived defaults aren’t acceptable.
Three outcomes depending on the caller’s state:
-
Fresh create (most common): a new WorkOS organization is created, the caller is added as
owner, the corporate domain is recorded as email-verified, and ToS / privacy-policy acceptance is logged from the request context. Returns{ success: true, organization: { id, name } }. -
Prospect adoption: an organization with the caller’s email domain already exists as a
prospect(the registry pre-recorded it from a brand crawl but no human had claimed it yet). The caller is promoted toownerof the existing record instead of forking a duplicate. Returns{ id, name, adopted: true }. -
Already-active conflict: the org exists and is already claimed by another paying member or a previously joined user. Returns
409with the existing org id so the caller can switch to a join-request flow (POST /api/organizations/:orgId/join-requests) instead of trying to register a duplicate.
Tier transitions happen via the billing flow only — there is no membership_tier field on this endpoint. After org creation, send the user to POST /api/checkout-session (or the /dashboard/membership page) to start a subscription; the Stripe webhook is the sole writer of organizations.membership_tier.
Rate-limited per user: 15 failed attempts per hour; successful calls do not count against the limit so a legitimate registration is never penalized by earlier validation errors.
curl --request POST \
--url https://agenticadvertising.org/api/organizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organization_name": "Acme Media",
"is_personal": false,
"marketing_opt_in": false
}
'import requests
url = "https://agenticadvertising.org/api/organizations"
payload = {
"organization_name": "Acme Media",
"is_personal": False,
"marketing_opt_in": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({organization_name: 'Acme Media', is_personal: false, marketing_opt_in: false})
};
fetch('https://agenticadvertising.org/api/organizations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agenticadvertising.org/api/organizations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'organization_name' => 'Acme Media',
'is_personal' => false,
'marketing_opt_in' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agenticadvertising.org/api/organizations"
payload := strings.NewReader("{\n \"organization_name\": \"Acme Media\",\n \"is_personal\": false,\n \"marketing_opt_in\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agenticadvertising.org/api/organizations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"organization_name\": \"Acme Media\",\n \"is_personal\": false,\n \"marketing_opt_in\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agenticadvertising.org/api/organizations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"organization_name\": \"Acme Media\",\n \"is_personal\": false,\n \"marketing_opt_in\": false\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"organization": {
"id": "org_01HXZAB123",
"name": "Acme Media"
},
"id": "<string>",
"name": "<string>",
"adopted": true
}{
"success": true,
"organization": {
"id": "org_01HXZAB123",
"name": "Acme Media"
},
"id": "<string>",
"name": "<string>",
"adopted": true
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Authorizations
Bearer token in the Authorization header. Two token types are accepted:
- Organization API key (
sk_...) issued via the dashboard. Org-scoped, long-lived, for server-to-server use. - User JWT obtained via the OAuth 2.1 authorization code flow with PKCE. User-scoped, short-lived. Discover the authorization server at
/.well-known/oauth-authorization-serverand the protected-resource metadata at/.well-known/oauth-protected-resource/api.
Body
Request body for POST /api/organizations.
Bootstraps a WorkOS organization, mirrors the caller as owner, records the caller's ToS / privacy-policy acceptance, and (for non-personal orgs) inserts an email-verified record into organization_domains so subsequent registry calls can skip explicit domain-verification.
Membership tier and corporate domain are not caller-supplied: the tier is set by the Stripe webhook on subscription events, and the corporate domain is derived from the authenticated user's email.
Response
Prospect adoption — an existing prospect organization for this domain was claimed by the caller. Body is { id, name, adopted: true }.
Response from POST /api/organizations. The body shape varies by path: a fresh creation returns { success: true, organization: { id, name } }; a prospect adoption returns { id, name, adopted: true } directly. Both paths are 2xx; downstream callers should treat any 2xx as "the org now exists and you are an owner of it" and read whichever id is present.
Was this page helpful?