Organizations

An Organization is the top-level entity in Transcodely. It represents a company, team, or individual account and serves as the billing boundary for all usage.

Overview

Organizations own one or more Apps, which in turn contain all your API keys, origins, presets, and jobs. Every charge on your invoice rolls up to the organization level.

curl -X POST https://api.transcodely.com/transcodely.v1.OrganizationService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "slug": "acme-corp",
    "display_name": "Acme Corporation",
    "billing_email": "billing@acme.com",
    "currency": "EUR"
  }'

const org = await client.organizations.create({
  slug: "acme-corp",
  displayName: "Acme Corporation",
  billingEmail: "billing@acme.com",
  currency: "EUR",
});
console.log(org.id);

org = client.organizations.create(
    slug="acme-corp",
    display_name="Acme Corporation",
    billing_email="billing@acme.com",
    currency="EUR",
)
print(org.id)

org, err := client.Organizations.Create(ctx, &transcodely.OrgCreateParams{
	Slug:         "acme-corp",
	DisplayName:  "Acme Corporation",
	BillingEmail: proto.String("billing@acme.com"),
	Currency:     proto.String("EUR"),
})
fmt.Println(org.GetId())

{
  "organization": {
    "id": "org_a1b2c3d4e5",
    "slug": "acme-corp",
    "display_name": "Acme Corporation",
    "billing_email": "billing@acme.com",
    "currency": "EUR",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

Slugs

Every organization has a unique, URL-safe slug used for identification alongside the org_ prefixed ID. Slugs are:

Immutable — cannot be changed after creation
Lowercase — automatically normalized
3-50 characters — must start with a letter
URL-safe — only lowercase letters, numbers, and hyphens (no consecutive hyphens)

Check slug availability before creating an organization:

curl -X POST https://api.transcodely.com/transcodely.v1.OrganizationService/CheckSlug 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{ "slug": "acme-corp" }'

const result = await client.organizations.checkSlug("acme-corp");
console.log(result.available, result.normalizedSlug);

result = client.organizations.check_slug("acme-corp")
print(result.available, result.normalized_slug)

result, err := client.Organizations.CheckSlug(ctx, "acme-corp")
fmt.Println(result.Available, result.Reason)

{
  "available": true,
  "normalized_slug": "acme-corp",
  "message": "Slug is available"
}

If a slug is taken or reserved, the response tells you why:

{
  "available": false,
  "normalized_slug": "acme-corp",
  "reason": "taken",
  "message": "This slug is already in use"
}

Organization Status

Organizations have a lifecycle represented by their status:

Status	Description	API Access
`active`	Normal operation	Full access
`suspended`	Blocked due to billing issue or admin action	All API requests return `403`
`deleted`	Soft-deleted, no access allowed	All API requests return `403`

Status transitions are managed by the platform. You cannot directly change an organization’s status through the API.

Currency

Each organization has a billing currency set at creation (default: EUR). This currency is used for all cost calculations, estimates, and invoices. The currency is specified as an ISO 4217 code (e.g., EUR, USD, GBP).

Updating an Organization

You can update the display name and billing email at any time. The slug and currency cannot be changed after creation.

curl -X POST https://api.transcodely.com/transcodely.v1.OrganizationService/Update 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "org_a1b2c3d4e5",
    "display_name": "Acme Corp International",
    "billing_email": "finance@acme.com"
  }'

const org = await client.organizations.update({
  id: "org_a1b2c3d4e5",
  displayName: "Acme Corp International",
  billingEmail: "finance@acme.com",
});

org = client.organizations.update(
    id="org_a1b2c3d4e5",
    display_name="Acme Corp International",
    billing_email="finance@acme.com",
)

org, err := client.Organizations.Update(ctx, &transcodely.OrgUpdateParams{
	Id:           "org_a1b2c3d4e5",
	DisplayName:  proto.String("Acme Corp International"),
	BillingEmail: proto.String("finance@acme.com"),
})

Listing Organizations

List all organizations your authenticated user has access to:

curl -X POST https://api.transcodely.com/transcodely.v1.OrganizationService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "pagination": { "limit": 20 }
  }'

for await (const org of client.organizations.list({
  pagination: { limit: 20 },
}).autoPage()) {
  console.log(org.id, org.slug);
}

for org in client.organizations.list(limit=20).auto_paging_iter():
    print(org.id, org.slug)

iter := client.Organizations.List(ctx, &transcodely.OrgListParams{
	Pagination: &transcodely.PaginationRequest{Limit: 20},
})
for iter.Next() {
	org := iter.Current()
	fmt.Println(org.GetId(), org.GetSlug())
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

Pass "include_inactive": true to include suspended and deleted organizations in the response.

Looking Up an Organization

The Get endpoint accepts either an organization ID or slug:

# By ID
curl -X POST https://api.transcodely.com/transcodely.v1.OrganizationService/Get 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{ "id_or_slug": "org_a1b2c3d4e5" }'

# By slug
curl -X POST https://api.transcodely.com/transcodely.v1.OrganizationService/Get 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{ "id_or_slug": "acme-corp" }'

// By ID
const byId = await client.organizations.get("org_a1b2c3d4e5");
// By slug
const bySlug = await client.organizations.get("acme-corp");

# By ID
by_id = client.organizations.get("org_a1b2c3d4e5")
# By slug
by_slug = client.organizations.get("acme-corp")

// By ID
byID, err := client.Organizations.Get(ctx, "org_a1b2c3d4e5")
// By slug
bySlug, err := client.Organizations.Get(ctx, "acme-corp")

If the value starts with org_, it is treated as an ID. Otherwise it is treated as a slug.

#Organizations

#Overview

#Slugs

#Organization Status

#Currency

#Updating an Organization

#Listing Organizations

#Looking Up an Organization