Contact - Create

Overview

Creates a new Contact record in the Biosafety Clearing-House and initiates the publishing workflow — identifier check, securities, validation, draft and workflow — in a single call.

Endpoint

POST /api/v2023/documents/schemas/contact

The identifier may also be supplied in the path — POST /api/v2023/documents/schemas/contact/:identifier? — otherwise it is taken from the document's header.identifier.

Headers

Header	Required	Description
Content-Type	Yes	Media type of the request body. The allowed value is application/json.
Authorization	Yes	Bearer token authenticating the request (Bearer <token>). Obtain it from the User - Authentication endpoint.
Accept	No	Format the client expects in the response. The allowed value is application/json.
Realm	No	The Clearing-House context. May be sent here instead of the realm query parameter.

Path Parameters

Parameter	Description
schema	The record type being published: contact.
identifier	Optional. The record's unique identifier; when omitted it is taken from the document's header.identifier.

Query Parameters

Parameter	Required	Description
realm	Yes	The Clearing-House context. For this application and environment: bch. May alternatively be sent as the Realm HTTP header.

Request Body

The request body is a JSON object with three top-level fields:

Field	Type	Required	Description
document	Object	Yes	The record itself — the fields listed below, wrapped in a document object (its header plus the record-type fields).
additionalInfo	String	No	Up to 1000 characters. Available only when a user with the NAU role submits a request to the Publishing Authority (PA) to publish a record.
batchId	String	No	Up to 100 characters. Batches multiple records together for publishing.

The fields of the document object are below. The record's identifier is taken from header.identifier; publishing fails if a record or draft with that identifier already exists.

Title	Field	Mandatory	Type	Example
	header		Header	{ "identifier": "068C83BA-995F-08C3-50CE-AD43545B3EB5", "schema": "contact", "languages": ["en"] }
Prefix	prefix		lstring	{"en":"Mr"}
First Name	firstName	True	string	John
Middle Name	middleName		string	Smith
Last Name	lastName	True	string	Doe
Gender	gender		Term
Job Title	designation		lstring	{"en":"Software"}
Organization	organization	True	lstring	{"en":"Test Organization"}
Acronym	organizationAcronym		lstring	{"en":"CSBD"}
Department / Division / Unit	department		lstring	{"en":"Division"}
Type of Organization	organizationType		Term	{"identifier":"86D464C3-B5BB-4B02-85E4-1AAD8D64CD27"}
Street Address	address		lstring	{"en":"560 Franklin"}
City	city		lstring	{"en":"Cambridge"}
State or Province	state		lstring	{"en":"Ontario"}
Postal Code or Zip	postalCode		lstring	{"en":"N1R 7Z1"}
Country of Contact	country	True	Term	{"identifier":"ca"}
Phone Number(s)	phones		string[]	["54825578896"]
Fax Number(s)	faxes		string[]	["123456"]
Email(s)	emails	True	string[]	["john.doe@example.com"]
Website Address(es)	websites		Link[]	[{"url":"http://www.example.com"}]
Address Type	addressType		string	organization
Relevant Information	relevantInformation		lstring
Relevant Documents	relevantDocuments		Link[]
Contact Type	type	True	string	person
Country	government		Term	{"identifier":"af"}
Organization	contactOrganization	True	Reference	{"identifier":"SIMP-22D52282-2FB2-AD2A-2965-476DFF6A7F37@1"}

Response

A successful call returns the saved draft and the publishing workflow that was started. Validation failures also return HTTP 200, with an errors array in the body instead — always check the response body, not just the status code.

When the document fails validation, the issues are returned in the errors property of the response (with HTTP 200). Each entry names the error code and the property it applies to:

{
  "identifier": "DECLARE-ORGANISATION_5885_20241031144831187",
  "errors": [
    { "code": "Error.Mandatory", "property": "government" }
  ]
}

Error Type	Description
Error.Mandatory	A required field is missing.
Error.MandatoryAnyOf	At least one field from a set of mandatory fields is missing.
Error.InvalidValue	The provided value is not valid according to the schema.
Error.InvalidProperty	An invalid property or field name.
Error.UnspecifiedLocale	A locale or language code is missing or invalid.
Error.UnexpectedTerm	An unexpected term or parameter.
Error.InvalidType	The provided data type is not valid.

Errors

The following error conditions may occur while interacting with the API. Each entry describes a specific error status code, along with an error message explaining the issue and any additional requirements for successful execution.

Status Code	Description
400	realm param is missing, please provide valid realm in querystring or httpHeaders.
400	Realm is not configured, please provide valid realm.
400	Schema not configured for the given realm.
400	A document with the identifier exists, please use a different identifier.
400	A document with the identifier does not exist, please provide correct identifier to update.
400	The record is locked for workflow, cannot proceed.
403	Insufficient rights to create a draft record.
403	Insufficient rights to update the draft record.
403	Authorization required, user is anonymous.

Playground

This playground connects to the production environment (api.cbd.int). Requests made here affect real, live data.

This is a protected route. To access this content, you need to be logged in. Logging in will provide you with an authentication token, which is required for making API calls.

Swagger playground is loading, please wait...

An error occurred while loading Swagger playground, please refresh the page.

Legacy alternative. Publishing through the legacy v2013 API uses the Save Draft endpoint plus a workflow call; new integrations should use this single v2023 call instead. The record's other draft operations (drafts, locks, securities, validation, versions) are documented under Draft Operations.