Create a trip via the API

Run it in Postman

Prefer to click through it? The same happy path is available as a Postman collection that chains the token, user ID, and trip ID automatically between requests.

1. Download premote-api-workflow.postman_collection.json — or, in Postman, choose Import → Link and paste that same URL.
2. Set the collection variables clientId and clientSecret (from Settings → API access).
3. Run the requests top-to-bottom, or use the Collection Runner.

1. Get a bearer token

Exchange your API credentials (generated in Settings → API access) for a short-lived bearer token using the OAuth 2.0 client-credentials flow.

POST /auth/token — API Reference

curl -X POST https://api.premote.io/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "prm_live_...",
    "client_secret": "prm_secret_..."
  }'

Response:

{ "access_token": "eyJhbGciOi..." }

Send the token as Authorization: Bearer <access_token> on every subsequent request.

2. Find the traveler

Before creating a user, check whether they already exist (users are also provisioned via HRIS sync, so most travelers are already present).

GET /users/list — API Reference

curl https://api.premote.io/v1/users/list \
  -H 'Authorization: Bearer <token>'

Match the traveler by email in the returned list and note their id.

3. Create the traveler (if not found)

If the traveler doesn't exist, create them. This endpoint requires a company super-admin token.

POST /users — API Reference

curl -X POST https://api.premote.io/v1/users \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe"
  }'

The response is the created user. Keep its id — you'll use it as the travelerId.

4. Complete the traveler's profile

Trips can only be created once the traveler's required profile fields are filled. Save profile values with:

POST /users/{id}/data — API Reference

curl -X POST https://api.premote.io/v1/users/123/data \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "nationality": "DE",
    "date_of_birth": "1990-04-12"
  }'

The body is a flat map of field_key → value. To discover which fields exist and which are still missing, use the next step.

5. List profile fields and check completeness

GET /user-fields/profile/USERID — API Reference — returns the traveler's profile fields grouped by category. Use it to learn which keys to send in step 4, and to confirm the required ones are filled.

curl https://api.premote.io/v1/user-fields/profile/123 \
  -H 'Authorization: Bearer <token>'

Repeat steps 4–5 until every required profile field has a value.

6. Discover the trip fields

GET /trip-fields — API Reference — returns the trip fields available to your company, grouped by category. These are the keys you can send in the trip's values object. Optionally narrow them to a trip type.

curl 'https://api.premote.io/v1/trip-fields?tripType=BUSINESS_TRIP' \
  -H 'Authorization: Bearer <token>'

7. Check trip completeness

Before creating the trip, you can check which trip/profile fields a set of draft values is still missing for a given traveler:

POST /trips/completeness/USERID — API Reference

curl -X POST https://api.premote.io/v1/trips/completeness/123 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BUSINESS_TRIP",
    "destination": "FR",
    "start_date": "2026-09-01",
    "end_date": "2026-09-05"
  }'

Response:

{
  "missingUserFields": [],
  "missingTripFields": [],
  "wrongUserFields": [],
  "wrongTripFields": []
}

When all four arrays are empty, the trip is ready to create.

8. Create the trip

POST /trips/multiple — API Reference — creates one trip per traveler ID. travelerIds is required — pass a single-item array containing the user you found or created in steps 2–3.

curl -X POST https://api.premote.io/v1/trips/multiple \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "travelerIds": [123],
    "type": "BUSINESS_TRIP",
    "values": {
      "origin": "DE",
      "destination": "FR",
      "start_date": "2026-09-01",
      "end_date": "2026-09-05",
      "travel_reason": "CLIENT_MEETING"
    },
    "externalId": "acme-trip-4471"
  }'

• travelerIds — array of traveler user IDs (one trip per ID). Required.
• values — trip field values, keyed by field (see step 6).
• type — the trip type.
• externalId — (optional) your own identifier, stored against the trip.

The response is the created trip(s).

9. Fetch the result

Retrieve the full trip object — including its risk assessment — by ID:

GET /trips/{id}/object — API Reference

curl https://api.premote.io/v1/trips/456/object \
  -H 'Authorization: Bearer <token>'

The response is the trip flattened into a single object: stable envelope fields (id, status, type, travelerId, origin, destination, startDate, endDate, riskResult, …) plus the trip's field values inlined as additional camelCase keys (these vary per company — the keys come from step 6).

Recap