Standard response format

XPKit endpoints respond with JSON.

Endpoints managing individual resources

If accessing an individual resource (reading, updating, creating) XPKit responds in this format:

{
    "resource_url": "/api/{% resource_name: str %}/{% resource_id: str %}/",
    "resource_id": "{% resource_id: str %}",
    "resource": {}
}

Example

{
    "resource_url": "/api/activity/01c5e3ae-21ea-465a-bbe3-b0c81fba7762/",
    "resource_id": "01c5e3ae-21ea-465a-bbe3-b0c81fba7762",
    "resource": {
        "created": "2021-02-20T15:37:22Z",
        "activity_type": "registration",
        "last_modified": "2021-02-20T15:37:23Z",
        "owner_id": "e412a161-a58d-44cc-aab1-9696974f8758",
        "payload": {
            "object_id": "website"
        },
        "experience_id": "test-event-in-london"
    }
}

Endpoints managing collections of resources

If a listing endpoint is called, results are paginated in this format:

{
    "results": [],
    "count": {% total_docs_matching_criteria: int %},
    "next": {% next_page: int %},
    "next_token": {% next_page: str %},
    "previous": {% previous_page: int %},
    "previous_token": {% next_page: str %}
}

Note: see pagination options for details on the differences between page numbers and tokens and when to use each.

Example

{
    "results": [
        {
            "resource_url": "/api/activity/01c5e3ae-21ea-465a-bbe3-b0c81fba7762/",
            "resource_id": "01c5e3ae-21ea-465a-bbe3-b0c81fba7762",
            "resource": {
                "created": "2021-02-20T15:37:22Z",
                "activity_type": "registration",
                "last_modified": "2021-02-20T15:37:23Z",
                "owner_id": "e412a161-a58d-44cc-aab1-9696974f8758",
                "payload": {
                    "object_id": "website"
                },
                "experience_id": "test-event-in-london"
            }
        },
        {
            "resource_url": "/api/activity/434f345e-c804-4d37-a8ff-c6241494e57e/",
            "resource_id": "434f345e-c804-4d37-a8ff-c6241494e57e",
            "resource": {
                "created": "2021-02-20T14:30:34Z",
                "activity_type": "completed-game",
                "last_modified": "2021-02-20T14:30:34Z",
                "owner_id": "92f60cbf-0b7b-4f29-82fb-bf57b2baa9e5",
                "payload": {
                    "object_id": "vr-game"
                },
                "experience_id": "vr-experience-2021"
            }
        }
    ],
    "count": 6773,
    "previous": null,
    "previous_token": null,
    "next": 2,
    "next_token": "eyJwYWdlIjogMiwgImNyZWF0ZWQiOiAiMjAyMi0wMy0yMVQwNDoxNjo0OS42MTUyMDYrMDA6MDAifQ=="
}

Endpoints calling asynchronous jobs on resources

If an endpoint is called that starts an asynchronous job (i.e. triggering a notification, or requesting a data export) the result will not be available immediately. An acknowledgement response will be returned containing a Job ID:

{
    "job_id": "cd031d8d-96b3-4250-baa4-c91e3b1f520a",
    "info": "Received request. Processing.",
    "status": "https://jobs.{% base_domain %}/api/job/cd031d8d-96b3-4250-baa4-c91e3b1f520a/"
}

For endpoints that start multiple asynchronous jobs in one call (for example the export API can create multiple jobs in a recurring export request), the response will be an JSON array of the above objects.

If your application has been granted access to the job resource, specifically assigned the jobs:read scope, it will be able to call the status URL to check on the progress of the job(s).