Stakeholder Commitment - Create

Overview

Creates a new Stakeholder Commitment record in the Online Reporting Tool and initiates the publishing workflow — identifier check, securities, validation, draft and workflow — in a single call.

Endpoint

POST /api/v2023/documents/schemas/stakeholderCommitment

The identifier may also be supplied in the path — POST /api/v2023/documents/schemas/stakeholderCommitment/: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: stakeholderCommitment.
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: ort. 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": "stakeholderCommitment", "languages": ["en"] }
First Name	firstName	True	string	John
Last Name	lastName	True	string	Doe
Designation	designation	True	lstring	{"en":"Software Engineer"}
Department	department	True	lstring	{"en":"Division"}
Organization	organization	True	lstring	{"en":"Test Organization"}
Organization acronym	organizationAcronym		lstring	{"en":"CSBD"}
Type of Organization	organizationType	True	Term
Jurisdiction	jurisdiction	True	Term
Countries	jurisdictionCountries	True	Term[]	{"identifier":"af"}
Regions	jurisdictionRegions	True	Term[]
Title of commitment	title	True	lstring
Description of commitment	description	True	lstring
Start date	timelineStartDate	True	DateTime
End date (if applicable)	timelineEndDate	True	DateTime
Alternatively, indicate whether the commitment is open-ended	isOpenEnded	True	Boolean
Share information on plans for next steps	nextStepsInformation	True	lstring
Key performance indicators...	performanceInformation		lstring
CountryReviews...	endorsementsInformation		lstring
Primary National Target	primaryGlobalAlignment	True	Term
Primary global target	primaryNationalTarget	True	Reference
Other Global Alignment(s)	otherGlobalAlignments		Term[]
Other national target(s)	otherNationalTargets		Reference[]
Alignment Information	alignmentInformation		lstring
Indicators	indicators		Term[]
Elements of the Framework	implementingConsiderations		Term[]
Coverage Countries	coverageCountries		Term[]	{"identifier":"af"}
Coverage Regions	coverageRegions		Term[]
Coverage Other	coverageOther		lstring[]
Funding to be used towards meeting the commitment	fundingSource		lstring	funding source
Is the funding sufficient for achieving the commitment?	isFundingSufficient	True	Boolean
International Frameworks	internationalFrameworks		lstring
Partners	partners		lstring
Is Linked To NBSAP	isLinkedToNbsap		Boolean
Linked To NBSAP Countries	linkedToNbsapCountries		Term[]	{"identifier":"af"}
Will you report or provide information on Target 15 of the Framework?	isReportingOnTarget15	True	Boolean
Please provide details on what and how you will report or provide	target15Information	True	lstring
Is progress towards the commitment tracked?	isProgressTracked	True	Boolean
What is the format...	progressInformation	True	lstring
Provide a web address, if available	progressTrackingUrl		lstring	https://example.com
Potential ways to address challenges and opportunities...	implementationStrategies		lstring
Provide any other relevant information...	additionalInformation		lstring
Other relevant website address or attached documents	additionalDocuments		Link[]
Linked Documents	linkedAttachments		Link[]	[{"url":"https://example.com","name":"Attachment"}]
Notes	notes		string	Example notes

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.