# Planning Receive API

## Context

The Planning Receive API is a unified interface where you post your planning to. You should be aware of the format
we would expect from you.

## Environment

For the Planning Receive API we use the following URIs:

Production URL :


```
https://planning-receive-api.services.simacan.com/trips/insertOrUpdate
```

Staging URL :


```
https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate
```

OTM5 Production URL :


```
https://planning-receive-api.services.simacan.com/otm/api/v5/trips
```

OTM5 Staging URL :


```
https://planning-receive-api-stg.services.simacan.com/otm/api/v5/trips
```

## Schema

The planning-receive-api supports two type of planning formats:

1. OpenTripModel version 5, which is an [open standard](https://otm5.opentripmodel.org/) we support within Simacan.
2. 'schema-less' endpoints for XML, JSON and CSV. Where we accept any file with those formats and do not check for any schema at all.


You can find the exact details on our [OpenAPI specification page](https://planning-receive-api.services.simacan.com).

## Example

### Sending your planning

As mentioned before, you should have requested your access_token from the Auth API. Next, make sure you are setting
the correct headers and request type for the filetype you are sending, so set your `Content-Type` to one of the following:

| Filetype | Content-Type | Request type |
|  --- | --- | --- |
| csv | `text/csv` | POST |
| json | `application/json` | PUT |
| xml | `text/xml` | POST |


- For more info on the structure for the CSV file, [see our guide](/docs/universal-planning-inbox/planning-csv)
- For more info on the structure for the JSON file, [see our other guide](/assets/planning-otm5_new.9ff2080a3c67e4607dfd596dd6c4261a6b851de11b6813b7c8fe27a1d2bad756.1db55730.mdx)


#### Send it

Keep in mind that this request only works, if you have a bearer token and set the correct
Content-Type. Include these in the header. The content of the request should be in the body of the message.
In this example we post to the staging URL:

CSV

```shell
curl 
  --header "Content-Type: text/csv" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "trip ID,STOP ID,location ID,start time stop,END time stop
1,Stop1,1,2021-01-25T10:00:00+01:00,2021-01-25T10:00:00+01:00
1,Stop2,2,2021-01-25T10:45:00+01:00,2021-01-25T11:00:00+01:00
1,Stop3,1,2021-01-25T11:30:00+01:00,2021-01-25T11:45:00+01:00" \
  --request POST \
  https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate
```

JSON

```shell
curl 
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "{
    \"id\": \"2a8af6c6-e4d5-5dfb-9532-e8b17c3ffd88\",
    \"name\": \"2021-32-2-888\",
    \"externalAttributes\": {},
    \"actors\": [],
    \"actions\": []
    }"
  --request PUT \
  https://planning-receive-api-stg.services.simacan.com/otm/api/v5/trips
```

XML

```shell
curl 
  --header "Content-Type: text/xml" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "YOUR_XML_DATA_HERE" \
  --request POST \
  https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate
```

#### Response

If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this


```
01b44637-1395-4591-a0ec-14108022b707
```

*Great! Your planning has been delivered to our platform.* On success you will get the UUID for the specific file you've
just sent us. Keep in mind, this is just a confirmation that we received your file. This is not a confirmation that
your planning is processing.

To see the status of your delivered file, check the next chapter on the [Planning Status API](/docs/universal-planning-inbox/planning-status).

### Responses

| Key | Description |
|  --- | --- |
| 200 | Ok |
| 401 | *Unauthorized* Whenever you will get a 401 status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired |
| 403 | *Forbidden* You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource. If you are sure you are using the correct account, please get in touch with us |
| 404 | *Not Found* Whenever you will get a 404, you are probably using a malformed or incorrect URL |
| 415 | *Unsupported Media File* The request's Content-Type is not supported. |