Uber Developers

UpsertGroup

POSThttps://api.uber.com/v1/business/organizations/{organization_id}/group

Privileged and Confidential This endpoint design has been confidentially shared with you. It is still under development and is subject to change without notice. Please do not share this document or API endpoint details with anyone who is not authorized to have access. For more information read about scopes.

¶ Use Case

The UpsertGroup endpoint allows you to create or update a group within an organization. We currently allow only 10 programs to be linked/un-linked with a group per API request. We support the following features as part of this API:

API is idempotent, i.e., identical requests will result in identical responses.
If groupUUID is provided in request or there already exists a group with the same name the existing group is updated, otherwise a new group is created.
Program uuids being passed is optional and not providing them will not modify any existing programs of the group.

¶ Authorization

The Upsert Groups endpoint requires an access_token using the client credentials (for 1P use-case) grant to business.employees scope.

If an application follows third party authentication, the upsert groups endpoint requires the client to get authorized using the authorization endpoint

¶ Path Parameters

Name	Type	Optional	Description
`organization_id`	string	No	Identifier for your organization.

¶ Request Parameters

Name	Type	Optional	Description
`group_uuid`	string	Yes(For create) No(For update)	UUID of the group to be updated. Can be skipped while creating a new group
`group_name`	string	Yes (For Update) No(For create)	The group name to be created/updated.
`group_description`	string	Yes	Simple group description visible to admins on the Uber for Business account
`program_uuids_to_add`	array	Yes	Array of program UUIDs to be linked with the group. Note that active programs for a given organization can be queried from the Get Programs for Organization endpoint
`program_uuids_to_remove`	array	Yes	Array of program UUIDs to be de-linked from the group

¶ Response Fields

Name	Type	Description
`group`	object	The group object.
`group.uuid`	string	Unique identifier of the group object.
`group.name`	string	Name of the group.
`programs`	array	A list of program objects. Note that active programs for a given organization can be queried from the Get Programs for Organization endpoint
`programs[].uuid`	string	Unique identifier of the program object
`programs[].name`	string	The program name.
`programs[].category`	string	The category of program. Below are the possible values: `RIDES` `EATS` `GUESTS` `VOUCHERS` `HEALTH`

¶ Example Request

curl -X POST -H "Authorization: Bearer <TOKEN>" \
  "https://api.uber.com/v1/business/organizations/<organization_id>/group"
  --data-raw '{
      "name": "Rides and Eats api group",
      "description": "api group with rides and eats program",
      "program_uuids_to_add": [
        "7cc63e44-475f-404d-b537-47de360f223a",
        "61fc0855-2956-4778-8a5d-15c6c519dc13"
      ]
    }'

¶ Example Response

Status-Code: 200 OK

{
  "group": {
    "uuid": "5e64f300-bcc1-4fab-981d-9a8503e43493",
    "name": "Rides and Eats api group",
    "programs": [
      {
        "uuid": "61fc0855-2956-4778-8a5d-15c6c519dc13",
        "name": "Commute",
        "category": "RIDES"
      },
      {
        "uuid": "7cc63e44-475f-404d-b537-47de360f223a",
        "name": "Eats2",
        "category": "EATS"
      }
    ]
  }
}

¶ Error Responses

HTTP Status	Code	Description
206	`UPSERT_GROUP_PROGRAM_LINK_FAILURE`	Partial error if program linking/de-linking fails
400	`BAD_REQUEST`	request specific message
401	`NOT_AUTHORIZED`	Caller not authorized to make this request
404	`NOT_FOUND`	Group not found during update
429	`rate_limited`	Rate limit exceeded
500	`INTERNAL_SERVER_ERROR`	We have experienced a problem