POST /api/v2/assets/{uid_asset}/hooks/ – KoboToolbox Primary API

Survey data - Rest Services

Changed on Jul 28, 2026

Add an external service to asset.

Where:

name and endpoint are required
active is True by default
export_type must be one of these values:
1. json (default)
2. xml
email_notification is a boolean. If true, User will be notified when request to remote server has failed.
auth_level must be one of these values:
1. no_auth (default)
2. basic_auth
subset_fields is the list of fields of the form definition. Only these fields should be present in data sent to remote server
settings.custom_headers is dictionary of custom header: value

For example:

    "settings": {
        "customer_headers": {
            "Authorization" : "Token 1af538baa9045a84c0e889f672baf83ff24"
        }

payload_template is a custom wrapper around %SUBMISSION% when sending data to remote server. It can be used only with JSON submission format.

For example:

    "payload_template": '{"fields": %SUBMISSION%}'

post/api/v2/assets/{uid_asset}/hooks/

Request

The document declares no server URL.
Auth: one of:
- HTTP basic
- API key in header Authorization

Path parameters

uid_assetstring required

UID of the parent assets

Request body

activeboolean

assetinteger required

auth_level'no_auth' | 'basic_auth'

no_auth - no_auth
basic_auth - basic_auth

date_modifiedstring date-time required

email_notificationboolean

endpointstring required

export_type'xml' | 'json'

xml - xml
json - json

failed_countinteger required

logs_urlstring uri required

namestring required

payload_templatestring nullable

pending_countinteger required

subset_fieldsstring[]

success_countinteger required

uidstring required

urlstring uri required

Example request

{
  "logs_url": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/hooks/hZzzeedWxQoFHgibsTCysv/logs/",
  "url": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/"
}

Response