Skip to main content

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.

kindRequired variant fieldsSetup behavior
TOURFOLD_APPplatform: IOS or ANDROIDdevice_identity_id may be bound during enrollment.
THIRD_PARTY_OSMANDNone beyond kindThe first intake report may bind device_identity_id. Platform defaults to UNKNOWN.
TRACKING_DEVICEdevice_identity_id, connection_profileHardware 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_methodRequired authentication block
NONENone; authentication blocks are absent.
OAUTHoauth with the token endpoint and client credentials.
BASICbasic with username and password.
API_KEY_HEADERapi_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 422 with a field-required sub-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 AUTH parameter keeps its stored value when a parameter with the same key and place already exists.
  • Switching a custom gateway's auth_method requires the new block's credential; a stored credential of another auth method never stands in for it.
  • Explicit null for 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 folder or document payload using kind.
  • Task interaction webhook snapshots select options for single_choice or max_length for free_text. Answer metadata remains redacted: free-text answers and comments are not included.
  • Workflow title tokens use literal, record_field, trigger_field, or output_field. Literal tokens expose text; 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.