# External data source

Source is described by these properties:

| ​       | ​                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| url     | Absolute or relative URL pointing to document containing the data.                                                                                                   |
| method  | HTTP method used to request data. Can be “get” or “post”.                                                                                                            |
| service | Service type, required if relative URL is specified. If set then data is provided by specified service. Service base URL is used to build full URL to data document. |

## GET <a href="#get" id="get"></a>

### external data via GET <a href="#external-data-via-get" id="external-data-via-get"></a>

```
"source": { "url": "http://example.com/external.json", "method": "get" }
```

The platform sends GET request to specified URL and expects data as a response.‌

## POST <a href="#post" id="post"></a>

### external data via POST <a href="#external-data-via-post" id="external-data-via-post"></a>

```
"source": { "url": "http://example.com/prefill.json", "method": "post" }
```

The Interaction Cloud sends POST request to specified URL with project, event (if the field attached to event or element) and element (if the field attached to element) custom fields values.‌

### Request data <a href="#request-data" id="request-data"></a>

```javascript
{
    "project_id": "605b68ae-3efd-4edd-8139-84cbbcd20b3f",
    "project": 
    {
        "custom_fields": 
        {
            "competition_id": "1234",
            "twitter_hash_tag": "#lvis"
        }
    },
    "event_id": "851193bd-095b-478f-9b94-a8d7155f2603",
    "event": 
    {
        "custom_fields": 
        {
            "channel": "c4"
        }
    },
    "element": 
    {
        "content_type": "man_of_the_match",
        "custom_fields": 
        {
            "team_id": "234",
            "podium": [{
                "id": "p1",
                "data": "payload"
            }]
        }
    }
}
```

If request can not successfully return data it should return non-200 HTTP code and a body like this:‌

### Error response body <a href="#error-response-body" id="error-response-body"></a>

```javascript
{
    "missing_fields":
    {
        "project": ["competition_id"],
        "event": ["channel_id", "twitter_hash_tag"],
        "element": ["team_id"]
    },
    "error": "Unknown match id 1234"
}
```

Both `missing_fields` and `error` are optional.‌

## POST via Service <a href="#post-via-service" id="post-via-service"></a>

```
"source": { "url": "/prefill.json", "method": "post", "service": "prefiller" }
```

Request URL is constructed as `<service base url>/prefill.json`.‌

The platform passes `instance_uuid` and `project_uuid` parameters via the query string with an instance id and project id respectively.

{% hint style="warning" %}
Is a service is used as a source, it must be specified as a required service in the app spec.
{% endhint %}