Headers
Some headers are required.Authorization
The Authorization header with your API Key as a Bearer Token for Authentication, such as:Authorization: Bearer <key>
Content-Type
Requests that include a JSON Body MUST send a JSON content type header. The header is required and no other value is allowed. As in:Content-Type: application/json
User-Agent
Requests must send a valid User-Agent header to identify the application or system making the request. For third party tools, please use the standard tool or product name, such a cURL or Postman. Headers must be between 3 and 255 characters and only contain printable ASCII characters. For custom code, please send an agent code with the company name, system name, and ideally a version number, such as: `User-Agent: softco-guestsync-1.34 Failure to send this header will result in a MISSING_USER_AGENT error, while an invalid agent format will return INVALID_USER_AGENT.Property ID
Every endpoint requires a property ID header so it can scope both authorization and data to that property. This is true even for ‘global’ data such as guests, as it’s often used to provide specific guest sorting based on the guests’ relationship with the property. The specific header and format is:Kyc-property-id: 28afbb85-2acd-4742-ba4f-78ce13d1e40f
The value is a UUID that you can get from your KYC contact.
Correlation IDs
The API is built for tracing and advanced logging, and you are encouraged to send an optional Kyc-correlation-id in any format you like, though its (ASCII only, no spaces - the specification is:^[A-Za-z0-9._=+/-]{1,128}$ — alphanumeric + -_. (UUID/base64url) + =+/ (standard base64))
as a type of ‘trace’ or logging ID - we will log it internally as we process your request, and also return it to you in the response. Such as:
Kyc-correlation-id: a-great-id-of-yours-1234
We will also LATER accept an optional W3C traceparent header, which we will log internally and also return back to you in the response. Such as:
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
Note that invalid traceparent headers will not generate a 400 error, per the W3C specification, and will instead start a new trace and return it to you.
Either of these will often help us troubleshoot a given request or issue, and are far easier to use than hunting for specific object IDs, guest names, etc. (especially as we do not log PII like names or phone numbers).
Throttling
Throttling and other system protection functions will also require additional headers in the future.Idempotency
The KYC APi is NOT currently guaranteed to be idempotent, however we plan on included idempotency elements over time. You can include an idempotency header for later use, similar to Stripe. Note that idempotency key must be unique per payload hash, so prevent re-use (which will generate a 409 error, IDEMPOTENCY_KEY_REUSED). Debouncing conconcurrency control may also later issue a 409 error, IDEMPOTENCY_KEY_IN_PROGRESS. The current Idempotency Key lifetime plan is 24 hours. The reserved key is: `Idempotency-Key: xxyyzzOther Headers
Future custom headers will have a kyc- prefix, per RFC 6648.Request Paths & Details
Trailing Slashes
The KYC API does NOT support trailing slashes (/) and will error if they are used. They are a bad practice and this is part of our focus on very strict and specified API implementation.Paths
The API uses standard REST paths, such as: /guests and /rooms.Noun/Id/Action
The API uses standard REST nouns, which are always PLURAL, with IDs as path variables, such as:- /users - Plural nouns to get lists
- /users/ - Plural noun, with an ID for a single object
- /reservation//check-in - Trailing functions for controller functions that act on an object
Casing
The API uses very specific best-practice casing - all variables are camelCase while all URLs are spine-case:- URL - Spine-case, such as
/user-preferences - Path variables - camelCase, such as
/users/{userId} - GET parameters - camelCase, such as
/users?firstName=bob - JSON variables - camelCase, such as
{“firstName”:”bob”}
Methods or Verbs
The API uses standard REST verbs, and note the use of the new QUERY verb:
All other verbs will error.
Caching
Do not cache API responses without discussion with KYC, and all responses will contain no-cache headers.Unknown Parameters or Fields
The API will error if you send additional or unknown parameters, or unknown JSON body fields.Request Parameters and Body
All request data elements, for paths, path IDs, GET parameters, and JSON data follow standard REST practices.Encoding
All data is either ASCII or UTF-8 encoded, and all URL-level elements are URL-encoded. Any non-ASCII or non-UTF-8 data will result in an error.Dates
All dates are ISO8601 format, in two ways:- Date Only - in YYYY-MM-DD format
- DateTime - with Z timezone, in YYYY-MM-DDTHH:mm:ssZ format - Always in UTC time.