User Journeys

Create User Journey

Create a User Journey

post/api/v2/user_journeys

Request body

transition_type'pre_offer' | 'offer' | 'post_offer' | 'onboarding' | 'offboarding'

expiration_datestring YYYY-MM-DD

custom_fieldsobject

Example request

{
  "transition_type": "pre_offer",
  "user_id": "69ae0e64b02bfe73a44ca479",
  "state": "approved",
  "expiration_date": "2026-01-01",
  "office_location_id": "69ae0e64b02bfe73a44ca479",
  "custom_fields": {
    "key1": "Hello",
    "key2": "World"
  },
  "documents": [
    {
      "document_type": "offer_letter",
      "document_number": "1234",
      "document_title": "Offer Letter",
      "document_description": "Offer Letter to the Joe",
      "attachments": [
        {
          "file_name": "abc.pdf",
          "file_content_base64": "WW91J3JlIGEgY3VyaW91cyBmZWxsb3cgOy0p"
        }
      ]
    }
  ]
}

Response

The request has succeeded and a new resource has been created as a result.

idstring uuid required

journey_idstring uuid required

user_idstring uuid required

transition_type'pre_offer' | 'offer' | 'post_offer' | 'onboarding' | 'offboarding' required

created_atstring YYYY-MM-DD required

expiration_datestring YYYY-MM-DD required

Example response

{
  "id": "69ae0e64b02bfe73a44ca479",
  "journey_id": "69ae0e64b02bfe73a44ca479",
  "user_id": "69ae0e64b02bfe73a44ca479",
  "transition_type": "pre_offer",
  "state": "approved",
  "created_at": "2026-01-01",
  "expiration_date": "2026-01-01",
  "office_location": {
    "id": "69ae0e64b02bfe73a44ca479",
    "external_ids": {
      "workday": "LOCATION-3-69"
    },
    "address1": "123 Main St",
    "address2": "Suite 200",
    "address3": "Building B",
    "city": "New York",
    "state": "NY",
    "region": "Northeast",
    "country": "USA",
    "postal_code": "10001",
    "time_zone": "NZT",
    "latitude": 3.12332,
    "longitude": 3.12332
  },
  "custom_field_values": [
    {
      "id": "1234",
      "value": "custom field value",
      "name": "custom field name",
      "key": "1234"
    }
  ]
}

Changes

Changed in 6 of the 19 revisions of this API.145534

Mar 20, 2026f30bd25c50fa11See the full diff
- ●
  added the new voided enum value to the state response property for the response status 201
  response-property-enum-value-added
- ○
  added the new voided enum value to the request property state
  request-property-enum-value-added
Mar 9, 2026fd9ba80475792See the full diff
- ○
  added Models.OfficeLocation to the office_location response property anyOf list for the response status 201
  response-property-any-of-added
- ○
  removed OfficeLocation from the office_location response property anyOf list for the response status 201
  response-property-any-of-removed
This revision also has 26 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Mar 9, 20263f638e7bcdd4135228See the full diff
- ▲
  request property state was restricted to a list of enum values
  request-property-became-enum
- ▲
  request property transition_type was restricted to a list of enum values
  request-property-became-enum
- ▲
  the custom_fields request property type/format changed from / to object/
  request-property-type-changed
- ▲
  the documents/items/attachments/items/file_content_base64 request property type/format changed from string/ to string/Base64
  request-property-type-changed
- ▲
  the office_location_id request property type/format changed from object/ to /
  request-property-type-changed
- ▲
  the state request property type/format changed from / to string/
  request-property-type-changed
- ▲
  the user_id request property type/format changed from string/ to /
  request-property-type-changed
- ▲
  added 'unevaluatedProperties' constraint to the request property custom_fields
  request-property-unevaluated-properties-added
- ▲
  the custom_field_values response's property type/format changed from / to array/ for status 201
  response-property-type-changed
- ▲
  the office_location response's property type/format changed from object/ to / for status 201
  response-property-type-changed
- ▲
  the state response's property type/format changed from / to string/ for status 201
  response-property-type-changed
- ▲
  removed the required property office_location/external_ids from the response with the 201 status
  response-required-property-removed
- ▲
  removed the required property office_location/id from the response with the 201 status
  response-required-property-removed
- ●
  removed CustomFieldsValueObject from the custom_fields request property allOf list
  request-property-all-of-removed
- ●
  removed UserJourneyState from the state request property allOf list
  request-property-all-of-removed
- ●
  removed the request property created_at
  request-property-removed
- ●
  removed the request property documents/items/attachments/items/responses
  request-property-removed
- ●
  removed the request property documents/items/expiry_date
  request-property-removed
- ●
  removed the request property documents/items/issued_date
  request-property-removed
- ●
  removed the request property documents/items/issuer
  request-property-removed
- ●
  removed the request property documents/items/issuer_city
  request-property-removed
- ●
  removed the request property documents/items/issuer_country
  request-property-removed
- ●
  removed the request property documents/items/issuer_state
  request-property-removed
- ●
  removed the request property journey_id
  request-property-removed
- ●
  removed the request property office_location_id/address1
  request-property-removed
- ●
  removed the request property office_location_id/address2
  request-property-removed
- ●
  removed the request property office_location_id/address3
  request-property-removed
- ●
  removed the request property office_location_id/city
  request-property-removed
- ●
  removed the request property office_location_id/country
  request-property-removed
- ●
  removed the request property office_location_id/external_ids
  request-property-removed
- ●
  removed the request property office_location_id/id
  request-property-removed
- ●
  removed the request property office_location_id/latitude
  request-property-removed
- ●
  removed the request property office_location_id/longitude
  request-property-removed
- ●
  removed the request property office_location_id/postal_code
  request-property-removed
- ●
  removed the request property office_location_id/region
  request-property-removed
- ●
  removed the request property office_location_id/state
  request-property-removed
- ●
  removed the request property office_location_id/time_zone
  request-property-removed
- ●
  removed the request property office_location_id/workday
  request-property-removed
- ●
  removed the optional property office_location/address1 from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/address2 from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/address3 from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/city from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/country from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/latitude from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/longitude from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/postal_code from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/region from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/state from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/time_zone from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property office_location/workday from the response with the 201 status
  response-optional-property-removed
- ●
  added the new approved enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new completed enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new declined enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new draft enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new needs_attention enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new offboarding enum value to the transition_type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new offer enum value to the transition_type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new onboarding enum value to the transition_type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new pending_approval enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new post_offer enum value to the transition_type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new pre_offer enum value to the transition_type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new rejected enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new rescinded enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new submitted enum value to the state response property for the response status 201
  response-property-enum-value-added
- ●
  added the new user_pending enum value to the state response property for the response status 201
  response-property-enum-value-added
- ○
  added the new optional request property expiration_date
  new-optional-request-property
- ○
  added UUID subschema #2 to the office_location_id request property anyOf list
  request-property-any-of-added
- ○
  added UUID subschema #2 to the user_id request property anyOf list
  request-property-any-of-added
- ○
  added the new approved enum value to the request property state
  request-property-enum-value-added
- ○
  added the new completed enum value to the request property state
  request-property-enum-value-added
- ○
  added the new declined enum value to the request property state
  request-property-enum-value-added
- ○
  added the new draft enum value to the request property state
  request-property-enum-value-added
- ○
  added the new needs_attention enum value to the request property state
  request-property-enum-value-added
- ○
  added the new offboarding enum value to the request property transition_type
  request-property-enum-value-added
- ○
  added the new offer enum value to the request property transition_type
  request-property-enum-value-added
- ○
  added the new onboarding enum value to the request property transition_type
  request-property-enum-value-added
- ○
  added the new pending_approval enum value to the request property state
  request-property-enum-value-added
- ○
  added the new post_offer enum value to the request property transition_type
  request-property-enum-value-added
- ○
  added the new pre_offer enum value to the request property transition_type
  request-property-enum-value-added
- ○
  added the new rejected enum value to the request property state
  request-property-enum-value-added
- ○
  added the new rescinded enum value to the request property state
  request-property-enum-value-added
- ○
  added the new submitted enum value to the request property state
  request-property-enum-value-added
- ○
  added the new user_pending enum value to the request property state
  request-property-enum-value-added
- ○
  removed CustomFieldsValueObject from the custom_field_values response property allOf list for the response status 201
  response-property-all-of-removed
- ○
  removed UserJourneyState from the state response property allOf list for the response status 201
  response-property-all-of-removed
- ○
  added OfficeLocation subschema #2 to the office_location response property anyOf list for the response status 201
  response-property-any-of-added
- ○
  the response property created_at became required for the status 201
  response-property-became-required
- ○
  the response property custom_field_values became required for the status 201
  response-property-became-required
- ○
  the response property office_location became required for the status 201
  response-property-became-required
- ○
  the response property state became required for the status 201
  response-property-became-required
- ○
  the response property transition_type became required for the status 201
  response-property-became-required
- ○
  the response property user_id became required for the status 201
  response-property-became-required
- ○
  added the required property expiration_date to the response with the 201 status
  response-required-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 31, 202533c1d595839522See the full diff
- ●
  removed the request property journey_type
  request-property-removed
- ●
  removed the optional property journey_type from the response with the 201 status
  response-optional-property-removed
- ○
  added the new optional request property transition_type
  new-optional-request-property
- ○
  added the optional property transition_type to the response with the 201 status
  response-optional-property-added
May 19, 2025805744a185fa1See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 11, 20246cde27481f551See the full diff
- ▲
  api path removed without deprecation
  api-path-removed-without-deprecation
This revision also has 68 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history