Create one branch and invite its first manager

POST

/admin/branches

const url = 'https://example.com/admin/branches';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"commandId":"example","branchCode":"example","expectedOrganizationRevision":1,"legalName":"example","displayName":"example","businessIdentity":{"jurisdiction":"KR","registrationNumber":"example"},"contact":{"email":"example","phoneNumber":"example"},"address":{"postalCode":"example","roadAddress":"example","detailAddress":"example"},"managerInvitation":{"email":"example","displayName":"example"},"initialLifecycleStatus":"onboarding","initialMembershipFeePolicy":{"policyVersion":"example","monthlyFeeAmount":1,"currencyCode":"KRW","effectiveFrom":"2026-04-15"},"reason":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/admin/branches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "commandId": "example", "branchCode": "example", "expectedOrganizationRevision": 1, "legalName": "example", "displayName": "example", "businessIdentity": { "jurisdiction": "KR", "registrationNumber": "example" }, "contact": { "email": "example", "phoneNumber": "example" }, "address": { "postalCode": "example", "roadAddress": "example", "detailAddress": "example" }, "managerInvitation": { "email": "example", "displayName": "example" }, "initialLifecycleStatus": "onboarding", "initialMembershipFeePolicy": { "policyVersion": "example", "monthlyFeeAmount": 1, "currencyCode": "KRW", "effectiveFrom": "2026-04-15" }, "reason": "example" }'

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 255 characters /.*\S.*/

Request Body^required

application/json

CreateBranchAndInviteManagerRequest

object

commandId

required

string

>= 1 characters <= 200 characters /\S/

branchCode

required

string

/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/

expectedOrganizationRevision

required

integer

legalName

required

string

>= 1 characters <= 200 characters /\S/

displayName

required

string

>= 1 characters <= 100 characters /\S/

businessIdentity

required

object

jurisdiction

required

Allowed value: KR

registrationNumber

required

string

/^[0-9]{10}$/

key

additional properties

contact

required

object

email

required

string

<= 254 characters /^[A-Za-z0-9_+%-]+(?:\.[A-Za-z0-9_+%-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/

phoneNumber

required

string

/^\+[1-9][0-9]{7,14}$/

key

additional properties

address

required

object

postalCode

required

string

/^[0-9]{5}$/

roadAddress

required

string

>= 1 characters <= 300 characters /\S/

detailAddress

required

One of:

string
null

string

>= 1 characters <= 300 characters /\S/

key

additional properties

managerInvitation

required

object

email

required

string

<= 254 characters /^[A-Za-z0-9_+%-]+(?:\.[A-Za-z0-9_+%-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/

displayName

required

string

>= 1 characters <= 100 characters /\S/

key

additional properties

initialLifecycleStatus

required

Allowed value: onboarding

initialMembershipFeePolicy

required

object

policyVersion

required

string

>= 1 characters <= 100 characters /\S/

monthlyFeeAmount

required

integer

<= 2147483647

currencyCode

required

Allowed value: KRW

effectiveFrom

required

string format: date

key

additional properties

reason

required

string

>= 1 characters <= 500 characters /\S/

key

additional properties

Responses

200

Exact replay returns the same branchId, revision and onboarding outcome

application/json

object

commandId

required

string

>= 1 characters <= 200 characters /\S/

actorId

required

string

>= 1 characters /\S/

reason

required

string

>= 1 characters <= 500 characters /\S/

commandFingerprint

required

string

/^[a-f0-9]{64}$/

branchId

required

string

>= 1 characters /\S/

branchCode

required

string

/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/

revision

required

Allowed value: 1

organizationRevision

required

integer

>= 1

lifecycleStatus

required

Allowed value: onboarding

operatorIdentityId

required

One of:

string
null

string

>= 1 characters /\S/

operatorIdentityDisposition

required

One of:

string
null

string

Allowed values: created attached

managerMembershipId

required

One of:

string
null

string

>= 1 characters /\S/

managerMembershipStatus

required

One of:

string
null

string

Allowed values: invited active

managerInvitationStatus

required

string

Allowed values: pending sent accepted retrying

authorizationRelationshipStatus

required

string

Allowed values: pending active retrying

authorizationRelationships

required

membershipFeePolicyId

required

One of:

string
null

string

>= 1 characters /\S/

membershipFeePolicyRevision

required

One of:

unknown
null

Allowed value: 1

membershipFeePolicyStatus

required

string

Allowed values: pending published retrying

sideEffects

required

auditEventId

required

string

>= 1 characters /\S/

outcomeStatus

required

string

Allowed values: completed repair_pending

idempotentReplay

required

boolean

repair

required

One of:

object
null

object

repairId

required

string

>= 1 characters /\S/

nextRetryAt

required

One of:

string
null

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9]\.[0-9]{3}Z$/

key

additional properties

allowedNextActions

required

Array<string>

>= 1 items unique items

Allowed values: complete_branch_profile configure_service_area resend_manager_invitation inspect_onboarding_repair

One of:

object
object

object

operatorIdentityId

string

>= 1 characters

operatorIdentityDisposition

Allowed values: created attached

sideEffects

array

One of:

object
object

object

managerMembershipId

string

>= 1 characters

managerMembershipStatus

Allowed values: invited active

sideEffects

array

One of:

object

managerInvitationStatus

Allowed value: sent

allowedNextActions

array

>= 3 items <= 3 items

sideEffects

array

One of:

object

authorizationRelationshipStatus

Allowed value: active

sideEffects

array

One of:

object

membershipFeePolicyId

string

>= 1 characters

membershipFeePolicyRevision

Allowed value: 1

membershipFeePolicyStatus

Allowed value: published

sideEffects

array

idempotentReplay

required

201

Branch, operator identity, membership and authorization relationships created

application/json

object

commandId

required

string

>= 1 characters <= 200 characters /\S/

actorId

required

string

>= 1 characters /\S/

reason

required

string

>= 1 characters <= 500 characters /\S/

commandFingerprint

required

string

/^[a-f0-9]{64}$/

branchId

required

string

>= 1 characters /\S/

branchCode

required

string

/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/

revision

required

Allowed value: 1

organizationRevision

required

integer

>= 1

lifecycleStatus

required

Allowed value: onboarding

operatorIdentityId

required

One of:

string
null

string

>= 1 characters /\S/

operatorIdentityDisposition

required

One of:

string
null

string

Allowed values: created attached

managerMembershipId

required

One of:

string
null

string

>= 1 characters /\S/

managerMembershipStatus

required

One of:

string
null

string

Allowed values: invited active

managerInvitationStatus

required

string

Allowed values: pending sent accepted retrying

authorizationRelationshipStatus

required

string

Allowed values: pending active retrying

authorizationRelationships

required

membershipFeePolicyId

required

One of:

string
null

string

>= 1 characters /\S/

membershipFeePolicyRevision

required

One of:

unknown
null

Allowed value: 1

membershipFeePolicyStatus

required

string

Allowed values: pending published retrying

sideEffects

required

auditEventId

required

string

>= 1 characters /\S/

outcomeStatus

required

string

Allowed values: completed repair_pending

idempotentReplay

required

boolean

repair

required

One of:

object
null

object

repairId

required

string

>= 1 characters /\S/

nextRetryAt

required

One of:

string
null

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9]\.[0-9]{3}Z$/

key

additional properties

allowedNextActions

required

Array<string>

>= 1 items unique items

Allowed values: complete_branch_profile configure_service_area resend_manager_invitation inspect_onboarding_repair

One of:

object
object

object

operatorIdentityId

string

>= 1 characters

operatorIdentityDisposition

Allowed values: created attached

sideEffects

array

One of:

object
object

object

managerMembershipId

string

>= 1 characters

managerMembershipStatus

Allowed values: invited active

sideEffects

array

One of:

object

managerInvitationStatus

Allowed value: sent

allowedNextActions

array

>= 3 items <= 3 items

sideEffects

array

One of:

object

authorizationRelationshipStatus

Allowed value: active

sideEffects

array

One of:

object

membershipFeePolicyId

string

>= 1 characters

membershipFeePolicyRevision

Allowed value: 1

membershipFeePolicyStatus

Allowed value: published

sideEffects

array

idempotentReplay

required

outcomeStatus

required

Allowed value: completed

202

Durable onboarding repair is pending for an external side effect

application/json

object

commandId

required

string

>= 1 characters <= 200 characters /\S/

actorId

required

string

>= 1 characters /\S/

reason

required

string

>= 1 characters <= 500 characters /\S/

commandFingerprint

required

string

/^[a-f0-9]{64}$/

branchId

required

string

>= 1 characters /\S/

branchCode

required

string

/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/

revision

required

Allowed value: 1

organizationRevision

required

integer

>= 1

lifecycleStatus

required

Allowed value: onboarding

operatorIdentityId

required

One of:

string
null

string

>= 1 characters /\S/

operatorIdentityDisposition

required

One of:

string
null

string

Allowed values: created attached

managerMembershipId

required

One of:

string
null

string

>= 1 characters /\S/

managerMembershipStatus

required

One of:

string
null

string

Allowed values: invited active

managerInvitationStatus

required

string

Allowed values: pending sent accepted retrying

authorizationRelationshipStatus

required

string

Allowed values: pending active retrying

authorizationRelationships

required

membershipFeePolicyId

required

One of:

string
null

string

>= 1 characters /\S/

membershipFeePolicyRevision

required

One of:

unknown
null

Allowed value: 1

membershipFeePolicyStatus

required

string

Allowed values: pending published retrying

sideEffects

required

auditEventId

required

string

>= 1 characters /\S/

outcomeStatus

required

string

Allowed values: completed repair_pending

idempotentReplay

required

boolean

repair

required

One of:

object
null

object

repairId

required

string

>= 1 characters /\S/

nextRetryAt

required

One of:

string
null

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9]\.[0-9]{3}Z$/

key

additional properties

allowedNextActions

required

Array<string>

>= 1 items unique items

Allowed values: complete_branch_profile configure_service_area resend_manager_invitation inspect_onboarding_repair

One of:

object
object

object

operatorIdentityId

string

>= 1 characters

operatorIdentityDisposition

Allowed values: created attached

sideEffects

array

One of:

object
object

object

managerMembershipId

string

>= 1 characters

managerMembershipStatus

Allowed values: invited active

sideEffects

array

One of:

object

managerInvitationStatus

Allowed value: sent

allowedNextActions

array

>= 3 items <= 3 items

sideEffects

array

One of:

object

authorizationRelationshipStatus

Allowed value: active

sideEffects

array

One of:

object

membershipFeePolicyId

string

>= 1 characters

membershipFeePolicyRevision

Allowed value: 1

membershipFeePolicyStatus

Allowed value: published

sideEffects

array

idempotentReplay

required

outcomeStatus

required

Allowed value: repair_pending

401

Bearer access token is required

application/json

BranchOnboardingProblem

object

status

required

integer

Allowed values: 401 403 409 422 503

code

required

string

Allowed values: authentication_required branch_create_forbidden validation_failed business_identity_conflict manager_invitation_conflict stale_organization_revision idempotency_payload_mismatch onboarding_dependency_unavailable

message

required

string

>= 1 characters

fieldErrors

required

Array<object>

object

fieldPath

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

currentOrganizationRevision

required

One of:

integer
null

integer

conflictingFieldPaths

required

Array<string>

unique items

retryable

required

boolean

key

additional properties

403

Actor lacks branch:create permission

application/json

BranchOnboardingProblem

object

status

required

integer

Allowed values: 401 403 409 422 503

code

required

string

message

required

string

>= 1 characters

fieldErrors

required

Array<object>

object

fieldPath

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

currentOrganizationRevision

required

One of:

integer
null

integer

conflictingFieldPaths

required

Array<string>

unique items

retryable

required

boolean

key

additional properties

409

Business identity, invitation, organization revision or replay payload conflicts

application/json

BranchOnboardingProblem

object

status

required

integer

Allowed values: 401 403 409 422 503

code

required

string

message

required

string

>= 1 characters

fieldErrors

required

Array<object>

object

fieldPath

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

currentOrganizationRevision

required

One of:

integer
null

integer

conflictingFieldPaths

required

Array<string>

unique items

retryable

required

boolean

key

additional properties

422

Branch identity, contact, address or invitation fields are invalid

application/json

BranchOnboardingProblem

object

status

required

integer

Allowed values: 401 403 409 422 503

code

required

string

message

required

string

>= 1 characters

fieldErrors

required

Array<object>

object

fieldPath

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

currentOrganizationRevision

required

One of:

integer
null

integer

conflictingFieldPaths

required

Array<string>

unique items

retryable

required

boolean

key

additional properties

503

A durable dependency repair could not be scheduled

application/json

BranchOnboardingProblem

object

status

required

integer

Allowed values: 401 403 409 422 503

code

required

string

message

required

string

>= 1 characters

fieldErrors

required

Array<object>

object

fieldPath

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

currentOrganizationRevision

required

One of:

integer
null

integer

conflictingFieldPaths

required

Array<string>

unique items

retryable

required

boolean

key

additional properties

Create one branch and invite its first manager

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

200

201

202

401

403

409

422

503

Request Body^required