Create an organisation at an address, or return the one there

Needs a platform credential: a key or token whose person holds a platform role, with the privileged tenants:write scope. A credential of an ordinary organisation member is refused whatever its scopes. The external identifier is the organisation's address, its slug. Answers 201 when it was created and 200 when it was already there.

Quire permissions

Credential scopes: tenants:write.

The acting subject must also be allowed to perform this action in the organisation.

PUT

https://your-organisation.quirelms.com/api/v1/tenants/ext:{external_id}

View as Markdown

Authorisation

apiKeyoptionalHTTP
oauth2optionalOAuth 2.0

Path parameters

external_idstringrequired
The external identifier, unique per tenant per type, as supplied by the system of record.

Header parameters

Quire-Versionoptionalstring
The dated API revision to serve this request at. Omitted, the request is served at the revision the credential was issued against. The response echoes the revision actually applied.

format: date
Idempotency-Keyoptionalstring
A caller-chosen key making this request safe to retry. A replay of a completed request returns the recorded response with Idempotency-Replayed: true. Reusing a key for a different request is refused.

maxLength: 255

Request bodyJSONrequired

namestringrequired
maxLength: 200, minLength: 1
admin_emailstringrequired
format: email, maxLength: 254, pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
admin_namestringrequired
maxLength: 200, minLength: 1
plan_codestringrequired
maxLength: 60, minLength: 1
parent_idoptionalstringornull
An organisation this one belongs under, on the same account.
2 variants
One of the following:
string
null
trialoptionalboolean
data_regionoptionalstring
maxLength: 20, minLength: 2

Returns

200

Success.

JSON

idstringrequired
slugstringrequired
namestringrequired
statusstringrequired
data_regionstringrequired
parent_idstring | nullrequired
created_atstringrequired
updated_atstringrequired

201

Success.

JSON

idstringrequired
slugstringrequired
namestringrequired
statusstringrequired
data_regionstringrequired
parent_idstring | nullrequired
created_atstringrequired
updated_atstringrequired
admin_passwordstring | nullrequired
The first administrator's password, shown once, when the address had no account yet.

401

The credential is missing, malformed, expired or revoked.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

403

The credential lacks the scope this operation requires, or the acting subject lacks the capability.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

404

No such resource, or none this credential is permitted to know about.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

409

The request conflicts with the current state, with a previous use of the same idempotency key, or with a concurrent write.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

422

The request was understood and its content is not valid. errors names each field.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

429

A rate limit or a concurrency cap was reached. Retry-After says when to try again.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

500

Something failed at our end. Quote request_id when reporting it.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

curl --request PUT \ --url https://your-organisation.quirelms.com/api/v1/tenants/ext:string \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "name": "string", "admin_email": "user@example.com", "admin_name": "string", "plan_code": "string", "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef", "trial": true, "data_region": "string" } '

{ "id": "string", "slug": "string", "name": "string", "status": "string", "data_region": "string", "parent_id": "string", "created_at": "string", "updated_at": "string", "admin_password": "string" }

{ "type": "http://example.com", "title": "string", "status": 0, "code": "string", "category": "validation", "detail": "string", "request_id": "string", "errors": [ { "path": "string", "code": "string", "detail": "string" } ], "retry_after": 0, "docs_url": "http://example.com" }