diff --git a/src/api-reference/request/v4.endpoints.participant-resources.markdown b/src/api-reference/request/v4.endpoints.participant-resources.markdown new file mode 100644 index 000000000..5d2fab99e --- /dev/null +++ b/src/api-reference/request/v4.endpoints.participant-resources.markdown @@ -0,0 +1,165 @@ +--- +title: Travel Request v4 - Participant Resources +layout: reference +--- +# Travel Request v4 - Participant Resources + +Manage participants and child requests attached to a Budget Request. + +## Get participants for a Budget Request + +This endpoint will enable to retrieve the list of participants of a Budget Request, as well as the child Requests for each of the participants. + +### Scopes + +`travelrequest.write` - Refer to [Scope Usage](./v4.get-started.html#scope-usage) for full details. + +### HTTP Request + +##### URI Template + +``` +GET {datacenter}/travelrequest/v4/requests/{requestUuid}/participants +``` + +#### Parameters + +Name|Type|Format|Description +---|---|---|--- +`requestUuid`|`string`|[RFC 4122]|**Required** The unique identifier of the Request. +`userId`|`string`|-|The unique identifier of the user getting the participants list. If empty when using a Company token the default system user will be assumed to perform the action. + +#### Headers + +`concur-correlationid` is a specific custom header used for technical support in the form of a [RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace](https://tools.ietf.org/html/rfc4122). + +#### Payload + +None. + +### HTTP Response + +#### HTTP Status Codes + +To learn more about response HTTP status codes for this API see [Travel Request v4 - HTTP Status Codes](./v4.response-codes.html). + +#### Payload + +[ParentRequestParticipant](./v4.endpoints.schemas.html#schema-parentrequestparticipant) + +### Example - One participant with two Child Requests and One participant without Child Request + +#### HTTP Request + +```shell +GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/participants +Accept: application/json +Authorization: Bearer {token} +Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f +``` + +#### HTTP Response + +```shell +200 OK +``` + +```json +[ + { + "participant": { + "id": "60dea1fd-489f-48b9-925f-0d62a5b48175" + }, + "requests": [ + { + "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4", + "id": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4", + "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}" + }, + { + "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5", + "id": "B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5", + "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}" + }, + ] + }, + { + "participant": { + "id": "72efb2ae-5a0e-59ca-b037-1e73b6c59286" + } + } +] +``` + +## Manage participants of a budget request + +This endpoint will enable to manage participants (add or remove them) from a Budget Request. + +### Scopes + +`travelrequest.write` - Refer to [Scope Usage](./v4.get-started.html#scope-usage) for full details. + +### HTTP Request + +##### URI Template + +``` +PATCH {datacenter}/travelrequest/v4/requests/{requestUuid}/participants +``` + +#### Parameters + +Name|Type|Format|Description +---|---|---|--- +`requestUuid`|`string`|[RFC 4122]|**Required** The unique identifier of the Request. +`userId`|`string`|-|The unique identifier of the user updating the participants list. **Required** when connecting with a Company token. If empty, a 400 `missingRequiredParam` error. + +#### Headers + +`concur-correlationid` is a specific custom header used for technical support in the form of a [RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace](https://tools.ietf.org/html/rfc4122). + +#### Payload + +[Request Participants For Patch](./v4.endpoints.schemas.html#schema-requestparticipantsforpatch) + +### HTTP Response + +#### HTTP Status Codes + +To learn more about response HTTP status codes for this API see [Travel Request v4 - HTTP Status Codes](./v4.response-codes.html). + +#### Payload + +None. + +### Example - adding and removing a participant to a Budget Request + +#### HTTP Request + +```shell +PATCH https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/participants +Content-Type: application/merge-patch+json +Accept: application/json +Authorization: Bearer {token} +Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f +``` + +```json +{ + "value": [ + { + "id": "8422A66-A9B0-1424-5802-0D9BCD4351D3" + }, + { + "id": "9C33FBA0-ACB7-4F85-83BD-FC0DF3A78522", + "@deleted": true + } + ] +} +``` + +#### HTTP Response + +```shell +204 No Content +``` \ No newline at end of file diff --git a/src/api-reference/request/v4.endpoints.policy-resources.markdown b/src/api-reference/request/v4.endpoints.policy-resources.markdown index 52aa0d480..9ee4eba17 100644 --- a/src/api-reference/request/v4.endpoints.policy-resources.markdown +++ b/src/api-reference/request/v4.endpoints.policy-resources.markdown @@ -63,14 +63,22 @@ Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f ```json [ { - "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A", - "id": "F4C8BD31CA9D4D6292795BE687EB9B2A", - "name": "Internal training Request policy" + "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A", + "id": "F4C8BD31CA9D4D6292795BE687EB9B2A", + "name": "Internal training Request policy", + "allowParticipants": false }, { - "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026", - "id": "F10E6059B5A14A4C80327FE387491026", - "name": "Client meeting Request policy" + "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026", + "id": "F10E6059B5A14A4C80327FE387491026", + "name": "Client meeting Request policy", + "allowParticipants": false, + }, + { + "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/98B49B2523DDAB41A182DD581C637415", + "id": "98B49B2523DDAB41A182DD581C637415", + "name": "Budget Event Request policy", + "allowParticipants": true } ] diff --git a/src/api-reference/request/v4.endpoints.schemas.markdown b/src/api-reference/request/v4.endpoints.schemas.markdown index a56645e4e..ae0521356 100644 --- a/src/api-reference/request/v4.endpoints.schemas.markdown +++ b/src/api-reference/request/v4.endpoints.schemas.markdown @@ -32,6 +32,7 @@ Name|Type|Format|Description `highestExceptionLevel`|`string`|-|The highest level of exception contained in this Request. Supported values: `WARNING`, `ERROR`, and `NONE` `href`|`string`|[RFC 3986]|Hyperlink to the resource for this Request. `id`|`string`|-|The unique identifier of the Request. +`isParentRequest`|`boolean`|-|Indicates whether this Request is a Budget Request. `lastModified`|`timestamp`|[RFC 3339] `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`|The date the Request was last modified. `mainDestination`|`object`|[`Location`](#location)|The main destination of the Request. `name`|`string`|-|The name of the Request. @@ -39,6 +40,8 @@ Name|Type|Format|Description `pendingApproval`|`boolean`|-|Indicates whether this Request is pending approval. `pnr`|`string`|-|The value of the pnr provided within the agency proposals by the travel agency. `policy`|`object`|[`ResourceLink`](#schema-resourcelink)|The policy that applies to the Request. +`parentRequestId`|`string`|-|Required if a Child Request is created, corresponds to the unique identifier of the Budget Request the Child Request will be linked to. +`parentRequest`|`object`|[`ResourceLink`](#schema-resourcelink)|If the Request is a Child Request, reference to the corresponding Budget Request. `requestId`|`string`|4 to 6 alphanumeric characters|The public key of the Request (unique per customer). `startDate`|`date`|[ISO 8601] `yyyy-MM-dd`|The start date of the Request. `startTime`|`time`|`HH:mm`|The start time of the Request. @@ -236,6 +239,27 @@ Name|Type|Format|Description `href`|`string`|[RFC 3986]|Hyperlink to the resource for this Request policy. `id`|`string`|-|The Request policy unique identifier. `name`|`string`|-|The name of the Request policy. +`allowParticipants`|`boolean`|-|Whether this policy can add participants (policy is a Budget Request). + +## Budget Request Participant + +Name|Type|Format|Description +---|---|---|--- +`participant`|`object`|[`ResourceLink`](#schema-resourcelink)|Participant of the Budget Request. +`requests`|`array`|[`ResourceLink`](#schema-resourcelink)|The list of Child Requests from the Participant associated to the Budget Request. + +## Request Participants For Patch + +Name|Type|Format|Description +---|---|---|--- +`value`|`array`|[`Request Participant For Patch`](#schema-requestparticipantforpatch)|The list of participants to be added or removed from the Budget Request. + +## Request Participant For Patch + +Name|Type|Format|Description +---|---|---|--- +`id`|`string`|[RFC 4122]|**Required** The Participant unique identifier. +`@deleted`|`boolean`|-|Whether the Participant should be added or deleted from the Budget Request. If false or not provided then the participant is added. ## Request Type diff --git a/src/api-reference/request/v4.response-codes.markdown b/src/api-reference/request/v4.response-codes.markdown index 9f24b40c5..51d9c21aa 100644 --- a/src/api-reference/request/v4.response-codes.markdown +++ b/src/api-reference/request/v4.response-codes.markdown @@ -8,6 +8,7 @@ HTTP Status Code|Response Body|Description ---|---|--- 200 OK|-|Your GET request succeeded. 201 Created|-|Your POST request succeeded. +204 No Content|-|Your PATCH request succeeded. 400 Bad Request|`badParam` the request has bad parameter(s) {requestName}|The name of the request doesn't have the expected format -|`invalidJson` invalid json structure|An input JSON structure couldn't be parsed -|`invalidDate` error while parsing date value {dateValue}|A date or datetime value couldn't be parsed