Typed resource variants
Some resources have a fixed set of variants with different fields. Their OpenAPI schemas use
oneOf with a required discriminator such as kind, type, or auth_method. Check that field
before accessing variant-specific properties. Each branch describes the complete object.
Devicesโ
Public device creation requires kind; omitting it does not select a default.
kind | Required variant fields | Setup behavior |
|---|---|---|
TOURFOLD_APP | platform: IOS or ANDROID | device_identity_id may be bound during enrollment. |
THIRD_PARTY_OSMAND | None beyond kind | The first intake report may bind device_identity_id. Platform defaults to UNKNOWN. |
TRACKING_DEVICE | device_identity_id, connection_profile | Hardware tracking must be enabled and the selected profile supported. |
{ "kind": "TOURFOLD_APP", "platform": "IOS", "description": "Delivery phone" }
device_model, phone_number, and description are optional. Only tracking hardware has
connection_profile. The response uses the same variants; tracking identity and profile are
required, while app and OsmAnd identities may still be absent during setup. Legacy app Devices
whose platform has not been discovered return platform: "UNKNOWN" and remain readable.
PATCH does not require resending kind. The existing kind determines validation: kind cannot
change, tracking identity and profile cannot be cleared, and explicitly setting an app platform
requires IOS or ANDROID. Omitted fields remain unchanged, including a legacy UNKNOWN
platform when editing another field. Explicit null clears an optional field where the
stored variant permits it; an existing identity cannot be replaced directly with a different one.
SMS gatewaysโ
type: "TWILIO" requires twilio_config; type: "CUSTOM_HTTP" requires custom_config.
Fields belonging to the other provider are rejected. PATCH can omit type; supplying a configuration
replaces that configuration and must match the stored provider.
Custom HTTP settings require an explicit auth_method, including NONE for unauthenticated endpoints:
auth_method | Required authentication block |
|---|---|
NONE | None; authentication blocks are absent. |
OAUTH | oauth with the token endpoint and client credentials. |
BASIC | basic with username and password. |
API_KEY_HEADER | api_key with header name and value. |
Each parameter has key, place, and type. place selects QUERY, HEADER, PATH, JSON_BODY,
or FORM_BODY. RECIPIENT takes its value from the message recipient and MESSAGE_VALUE from the
message text; neither accepts static_value. SENDER_NUMBER and EXTRA require a nonblank string
static_value. AUTH carries a credential in static_value and follows the write-only rules below.
There is no runtime extras fallback and missing fixed values are rejected before delivery.
Credentials are write-onlyโ
Provider credentials โ twilio_config.auth_token, twilio_config.account_auth_token,
oauth.client_secret, basic.password, api_key.header_value and the static_value of an AUTH
parameter โ are accepted on write but never returned. Responses replace each of them with a boolean
*_configured flag (auth_token_configured, client_secret_configured, password_configured,
header_value_configured, static_value_configured) that reports whether a value is stored. The
response schemas are StoredTwilioGatewayConfig, StoredCustomSmsSettings and
StoredCustomSmsParameter with their variants; the request schemas keep their original names.
- Create requires every credential of the chosen provider variant. A missing one returns a
field-level
422with afield-requiredsub-error, for example#/twilio_config/auth_token. - Update replaces the configuration as a whole, but a credential omitted from the new
configuration keeps its stored value. Provide a credential to rotate it. An
AUTHparameter keeps its stored value when a parameter with the samekeyandplacealready exists. - Switching a custom gateway's
auth_methodrequires the new block's credential; a stored credential of another auth method never stands in for it. - Explicit
nullfor a credential is treated like omission; credentials cannot be cleared.
Every stored credential is encrypted at rest. The audit log entry of an update lists the wire names
of the credentials it rotated under rotated_secrets, never their values.
Testing a gatewayโ
POST /api/v2/sms-gateways/{sms_gateway_id}/test sends a test message through the selected gateway
synchronously and returns 200 with a tracking_id once the gateway has accepted it. Delivery updates
arrive through the SMS_GATEWAY_TEST_RESULT:V1 server-sent event. When the provider refuses the
message โ rejected credentials, an invalid recipient, a 4xx from a custom endpoint โ the response is
422 with type https://problems.tourfold.com/sms/gateway-rejected; when the provider cannot be
reached or fails temporarily it is 503 with type
https://problems.tourfold.com/sms/gateway-unavailable. Both carry data.tracking_id for the FAILED
report entry and data.provider_status where the provider returned a status. Request validation
errors keep returning validation-failed.
{
"name": "Custom SMS",
"type": "CUSTOM_HTTP",
"custom_config": {
"url": "https://sms.example.com/send",
"http_method": "POST",
"auth_method": "NONE",
"parameters": [
{ "key": "to", "place": "JSON_BODY", "type": "RECIPIENT" },
{ "key": "text", "place": "JSON_BODY", "type": "MESSAGE_VALUE" },
{ "key": "sender", "place": "JSON_BODY", "type": "SENDER_NUMBER", "static_value": "Tourfold" }
]
}
}
Missing required fields and inapplicable variant fields return a field-level 422, including nested
pointers such as #/custom_config/parameters/0/static_value.
Other resource variantsโ
- Starred entries select a required
folderordocumentpayload usingkind. - Task interaction webhook snapshots select
optionsforsingle_choiceormax_lengthforfree_text. Answer metadata remains redacted: free-text answers and comments are not included. - Workflow title tokens use
literal,record_field,trigger_field, oroutput_field. Literal tokens exposetext; field tokens expose field-reference properties. Drafts may be incomplete; publishing applies the full workflow validation rules.
A discriminator is not a replacement for ordinary enums or arbitrary JSON values. Nullable PATCH
fields retain their omission/clear semantics, and JSON-valued fields retain meaningful explicit
null values. See write semantics and workflow versions.