Content Enrichment API / Approval Links
Create approval links (bulk)
PageMore page actions
POST /v2/project/content/createApprovalLinks
Mint one approval link per requested hotel that does not have a live one, and return the link of every requested member hotel in request order. The operation is idempotent: a hotel that already has a live link keeps it, token unchanged, so calling this again never invalidates a link that has already been sent out. A hotel whose link was REVOKED gets a fresh token instead — with Created true, its Status back to waiting_for_hotel (a new link means "look at this again"), and ApprovedAt, ApprovedBy and ApprovedTextGeneratedAt kept as the record of what was approved — which makes this the way back to a live link after a revoke. Created distinguishes minted from untouched per row. Hotel ids that are not live members of the project are skipped and echoed in NotInProjectIDs.
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/createApprovalLinks' \
-H "Authorization: Bearer $YGO_API_KEY" \
-H "X-Project-ID: $YGO_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"HotelIDs": [
"019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
"019d9c23-1238-7334-bf02-4c45c50e033a"
]
}'Authorization
Authorization: Bearer <key>
Project-scoped API key
Headers
X-Project-IDstring (uuid) requiredProject UUID. Required for all project-scoped endpoints.
Request body required
application/json object CreateApprovalLinksRequest
The hotels to mint approval links for.
HotelIDsarray of string (uuid) requiredUUIDs of the hotels to mint links for. Required, 1 to 500 entries, each a valid non-nil UUID. Duplicates are collapsed and the request order is preserved.
Example request: Mint links for two member hotels
{
"HotelIDs": [
"019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
"019d9c23-1238-7334-bf02-4c45c50e033a"
]
}Example request: One of the ids is not in the project
{
"HotelIDs": [
"019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
"019e4afb-e973-764c-9bb1-a4c66175e08b",
"019d9c23-1238-7334-bf02-4c45c50e033a"
]
}Example request: Mint a fresh link for a hotel whose link was revoked
{
"HotelIDs": [
"019d9c2e-0ef8-7458-b0fa-8bed7182eb30"
]
}Responses
200 OK
The approval links of every requested member hotel, in request order.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object CreateApprovalLinksResponse
List response envelope wrapping the links, plus the membership residue.
Dataarray of object ApprovalLink requiredOne entry per requested hotel that is a live member of the project, in request order. Always present, empty when no requested id was a member.
16 fields
HotelIDstring (uuid) requiredUUID of the hotel this link belongs to.
HotelNamestring requiredDisplay name of the hotel.
GiataIDintegerThe hotel's GIATA id. Omitted when the hotel has none.
MasterCodestringThe calling project's master code for this hotel. Omitted when the project has no code for it.
Tokenstring requiredThe 43-character link token — the full credential of the hotel's approval page. Build the link from it; do not log or display it.
TokenPreviewstring requiredDisplay form of the token: its first 8 characters followed by an ellipsis. Never enough to reconstruct the link.
Statusstring requiredApproval state of this hotel's link.
waiting_for_hotelon creation; any feedback moves it tofeedback_received;feedback_appliedis set once the feedback has been worked in;approvedis never left by a later feedback submission; the one way back towaiting_for_hotelis a re-minted link (createApprovalLinks after a revoke), which keeps ApprovedAt, ApprovedTextGeneratedAt and ApprovedBy as the record of the earlier approval.ApprovedAtstring (date-time)When the hotel approved (RFC3339). Present once the hotel has ever approved: it is the RECORD of that approval and survives a later revoke and a re-minted link, so it can accompany a
waiting_for_hotelStatus (see createApprovalLinks). Only a fresh approval replaces it.ApprovedTextGeneratedAtstring (date-time)Newest generation timestamp across the texts that were approved (RFC3339). Compare it with the hotel's current texts to see whether they changed since the approval. Present once the hotel has ever approved (it survives a revoke and a re-minted link, like ApprovedAt), and omitted then if none of the approved texts carried a timestamp.
ApprovedByobject ApprovalApproverPresent once the hotel has ever approved: the record of who signed off, kept across a later revoke and a re-minted link (so it can accompany a
waiting_for_hotelStatus) and replaced only by a fresh approval. The identity is the snapshot taken at approval time and survives deletion of the contact record (approved_byisON DELETE SET NULL; the snapshot columns are not cleared).3 fields
Namestring requiredThe contact's name.
Emailstring (email)The contact's email address.
PhonestringThe contact's phone number. Omitted when the contact did not supply one.
LastOpenedAtstring (date-time)When the approval page was last loaded (RFC3339). Omitted while the link has never been opened.
RevokedAtstring (date-time)When the link was revoked (RFC3339). Omitted while the link is live. A link carrying it is never returned with a
Token.Createdboolean requiredtrueonly when this call minted the credential inToken: a brand-new link, or a fresh one for a hotel whose link had been revoked.falsefor a hotel that already had a live link, and alwaysfalseon rotateApprovalLink, revokeApprovalLink and listApprovals.CreatedBystringAudit identity of who minted the link: a user token records the user's email; a project API key records its project-scoped identity (
project:<project-uuid>). That is what is STORED; what is RETURNED is gated. The stored identity is an operator identity by construction, so in practice it carries an internal staff email — a contact route, and therefore contact PII on the same footing asApprovedBy.EmailandApprovedBy.Phone: it is returned only to a caller presenting a user_ token, and is omitted entirely for a proj_ project token (the key is absent, not an empty string).CreatedAtstring (date-time) requiredWhen the link was minted (RFC3339).
UpdatedAtstring (date-time) requiredWhen the link row was last touched (RFC3339). The
updated_attrigger fires on every update, so this moves on a status transition, an approval and a token rotation — and also when the hotel merely opens the page, because that stampslast_opened_at. Do not use it to detect approval-state changes.
NotInProjectIDsarray of string (uuid)Requested hotel ids that are not live members of the calling project and were therefore skipped. Omitted when every requested id was a member.
Example response: Two links minted
{
"Data": [
{
"HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
"HotelName": "Sotavento Beach Club",
"GiataID": 5721,
"MasterCode": "FUED0009",
"Token": "xPBOjXHomqBvKZ0nQ2sT7yWlR4dGuAeIcNvXbF9pMk3",
"TokenPreview": "xPBOjXHo...",
"Status": "waiting_for_hotel",
"Created": true,
"CreatedBy": "editor@example.com",
"CreatedAt": "2026-08-25T18:19:17.522006Z",
"UpdatedAt": "2026-08-25T18:19:17.522006Z"
},
{
"HotelID": "019d9c23-1238-7334-bf02-4c45c50e033a",
"HotelName": "JAZ Makadina",
"GiataID": 16706,
"MasterCode": "HRGD0238",
"Token": "QxIpAvQhJ8rLzTd5oYuN1kSbVe6HcWfMg0iRnJ2aPtE",
"TokenPreview": "QxIpAvQh...",
"Status": "waiting_for_hotel",
"Created": true,
"CreatedBy": "editor@example.com",
"CreatedAt": "2026-08-25T18:19:17.522006Z",
"UpdatedAt": "2026-08-25T18:19:17.522006Z"
}
]
}Example response: Two links minted, the non-member id echoed back
{
"Data": [
{
"HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
"HotelName": "Sotavento Beach Club",
"GiataID": 5721,
"MasterCode": "FUED0009",
"Token": "xPBOjXHomqBvKZ0nQ2sT7yWlR4dGuAeIcNvXbF9pMk3",
"TokenPreview": "xPBOjXHo...",
"Status": "waiting_for_hotel",
"Created": true,
"CreatedBy": "editor@example.com",
"CreatedAt": "2026-08-25T18:19:17.522006Z",
"UpdatedAt": "2026-08-25T18:19:17.522006Z"
},
{
"HotelID": "019d9c23-1238-7334-bf02-4c45c50e033a",
"HotelName": "JAZ Makadina",
"GiataID": 16706,
"MasterCode": "HRGD0238",
"Token": "QxIpAvQhJ8rLzTd5oYuN1kSbVe6HcWfMg0iRnJ2aPtE",
"TokenPreview": "QxIpAvQh...",
"Status": "waiting_for_hotel",
"Created": true,
"CreatedBy": "editor@example.com",
"CreatedAt": "2026-08-25T18:19:17.522006Z",
"UpdatedAt": "2026-08-25T18:19:17.522006Z"
}
],
"NotInProjectIDs": [
"019e4afb-e973-764c-9bb1-a4c66175e08b"
]
}Example response: A revoked link re-minted: new token, Created true, status back to waiting_for_hotel, the approval record kept
{
"Data": [
{
"HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
"HotelName": "Sotavento Beach Club",
"GiataID": 5721,
"MasterCode": "FUED0009",
"Token": "tN4kQz8YbLm2VrXe7WcJd1SgHfU5oApIyB6nEt0RqZ3",
"TokenPreview": "tN4kQz8Y...",
"Status": "waiting_for_hotel",
"ApprovedAt": "2026-08-25T18:19:18.860882Z",
"ApprovedTextGeneratedAt": "2026-08-19T14:14:57.674681Z",
"ApprovedBy": {
"Name": "Ayşe Yılmaz",
"Email": "ayse@sotavento.example",
"Phone": "+34 928 000 000"
},
"LastOpenedAt": "2026-08-25T18:19:18.966928Z",
"Created": true,
"CreatedBy": "editor@example.com",
"CreatedAt": "2026-08-25T18:19:17.522006Z",
"UpdatedAt": "2026-08-25T18:19:20.114377Z"
}
]
}400 Bad Request
Bad Request - the request body or the X-Project-ID header failed validation.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredPath of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: X-Project-ID header missing
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "X-Project-ID header is required"
}
}Example response: Malformed request body
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Invalid request body"
}
}Example response: HotelIDs missing or empty
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelIDs",
"Message": "HotelIDs is required"
}
]
}
}Example response: More than 500 entries
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelIDs",
"Message": "HotelIDs may contain at most 500 entries"
}
]
}
}Example response: An entry is not a valid UUID
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelIDs",
"Message": "HotelIDs must contain valid UUIDs"
}
]
}
}401 Unauthorized
Unauthorized - Invalid or missing bearer token.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredPath of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: No Authorization header
{
"Error": {
"Code": "UNAUTHORIZED",
"Message": "Missing bearer token"
}
}Example response: The bearer token is not valid
{
"Error": {
"Code": "UNAUTHORIZED",
"Message": "Invalid bearer token"
}
}403 Forbidden
Forbidden - the caller is authenticated but may not act on this project. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.authoring:write permission this endpoint requires.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredPath of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: Missing required scope
{
"Error": {
"Code": "INSUFFICIENT_SCOPE",
"Message": "token lacks scope content.authoring:write"
}
}Example response: The user token has no editor access to the project
{
"Error": {
"Code": "FORBIDDEN",
"Message": "Access denied to project"
}
}Example response: The request carries no project scope
{
"Error": {
"Code": "FORBIDDEN",
"Message": "Project access required"
}
}404 Not Found
Not Found - the project or the hotel is not reachable for this caller.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredPath of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: The project does not exist or was deleted (user tokens)
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Project not found"
}
}Example response: A hotel could not be resolved while minting
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Hotel not found"
}
}429 Too Many Requests
Too Many Requests. The response includes a Retry-After header with the number of seconds to wait before retrying.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Retry-AfterintegerNumber of seconds to wait before retrying the request. Present on 429 responses.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredPath of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: Limit exceeded
{
"Error": {
"Code": "RATE_LIMIT_EXCEEDED",
"Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
}
}500 Internal Server Error
Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredPath of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: The links could not be minted
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to create approval links"
}
}Example response: Hotel membership could not be verified
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to verify hotels"
}
}