Upsert group attributions bulk

curl --request PUT \
  --url https://api.qobra.co/v1/users/groups/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "data": [
    {
      "user": "user-1@company.com",
      "group_dimension": "country",
      "group": "france",
      "start_date": "2023-01",
      "end_date": "2023-10"
    },
    {
      "user": "user-2@company.com",
      "group_dimension": "country",
      "group": "spain"
    },
    "..."
  ]
}
'

import requests

url = "https://api.qobra.co/v1/users/groups/bulk"

payload = { "data": [
        {
            "user": "user-1@company.com",
            "group_dimension": "country",
            "group": "france",
            "start_date": "2023-01",
            "end_date": "2023-10"
        },
        {
            "user": "user-2@company.com",
            "group_dimension": "country",
            "group": "spain"
        },
        "..."
    ] }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    data: [
      {
        user: 'user-1@company.com',
        group_dimension: 'country',
        group: 'france',
        start_date: '2023-01',
        end_date: '2023-10'
      },
      {user: 'user-2@company.com', group_dimension: 'country', group: 'spain'},
      '...'
    ]
  })
};

fetch('https://api.qobra.co/v1/users/groups/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.qobra.co/v1/users/groups/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        [
                'user' => 'user-1@company.com',
                'group_dimension' => 'country',
                'group' => 'france',
                'start_date' => '2023-01',
                'end_date' => '2023-10'
        ],
        [
                'user' => 'user-2@company.com',
                'group_dimension' => 'country',
                'group' => 'spain'
        ],
        '...'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qobra.co/v1/users/groups/bulk"

	payload := strings.NewReader("{\n  \"data\": [\n    {\n      \"user\": \"user-1@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"france\",\n      \"start_date\": \"2023-01\",\n      \"end_date\": \"2023-10\"\n    },\n    {\n      \"user\": \"user-2@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"spain\"\n    },\n    \"...\"\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.qobra.co/v1/users/groups/bulk")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": [\n    {\n      \"user\": \"user-1@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"france\",\n      \"start_date\": \"2023-01\",\n      \"end_date\": \"2023-10\"\n    },\n    {\n      \"user\": \"user-2@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"spain\"\n    },\n    \"...\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.qobra.co/v1/users/groups/bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": [\n    {\n      \"user\": \"user-1@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"france\",\n      \"start_date\": \"2023-01\",\n      \"end_date\": \"2023-10\"\n    },\n    {\n      \"user\": \"user-2@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"spain\"\n    },\n    \"...\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "import_id": "QfejsQZ6mpOVHT5Tt1SdNLPZ",
  "objects_imported": 2
}

{
  "count": 1,
  "errors": [
    {
      "error": "ValidationError",
      "resource": "data",
      "description": "Too many users, at most 200 can be sent per call"
    }
  ]
}

PUT

users

groups

bulk

Upsert group attributions bulk

curl --request PUT \
  --url https://api.qobra.co/v1/users/groups/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "data": [
    {
      "user": "user-1@company.com",
      "group_dimension": "country",
      "group": "france",
      "start_date": "2023-01",
      "end_date": "2023-10"
    },
    {
      "user": "user-2@company.com",
      "group_dimension": "country",
      "group": "spain"
    },
    "..."
  ]
}
'

import requests

url = "https://api.qobra.co/v1/users/groups/bulk"

payload = { "data": [
        {
            "user": "user-1@company.com",
            "group_dimension": "country",
            "group": "france",
            "start_date": "2023-01",
            "end_date": "2023-10"
        },
        {
            "user": "user-2@company.com",
            "group_dimension": "country",
            "group": "spain"
        },
        "..."
    ] }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    data: [
      {
        user: 'user-1@company.com',
        group_dimension: 'country',
        group: 'france',
        start_date: '2023-01',
        end_date: '2023-10'
      },
      {user: 'user-2@company.com', group_dimension: 'country', group: 'spain'},
      '...'
    ]
  })
};

fetch('https://api.qobra.co/v1/users/groups/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.qobra.co/v1/users/groups/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        [
                'user' => 'user-1@company.com',
                'group_dimension' => 'country',
                'group' => 'france',
                'start_date' => '2023-01',
                'end_date' => '2023-10'
        ],
        [
                'user' => 'user-2@company.com',
                'group_dimension' => 'country',
                'group' => 'spain'
        ],
        '...'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qobra.co/v1/users/groups/bulk"

	payload := strings.NewReader("{\n  \"data\": [\n    {\n      \"user\": \"user-1@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"france\",\n      \"start_date\": \"2023-01\",\n      \"end_date\": \"2023-10\"\n    },\n    {\n      \"user\": \"user-2@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"spain\"\n    },\n    \"...\"\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.qobra.co/v1/users/groups/bulk")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": [\n    {\n      \"user\": \"user-1@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"france\",\n      \"start_date\": \"2023-01\",\n      \"end_date\": \"2023-10\"\n    },\n    {\n      \"user\": \"user-2@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"spain\"\n    },\n    \"...\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.qobra.co/v1/users/groups/bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": [\n    {\n      \"user\": \"user-1@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"france\",\n      \"start_date\": \"2023-01\",\n      \"end_date\": \"2023-10\"\n    },\n    {\n      \"user\": \"user-2@company.com\",\n      \"group_dimension\": \"country\",\n      \"group\": \"spain\"\n    },\n    \"...\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "import_id": "QfejsQZ6mpOVHT5Tt1SdNLPZ",
  "objects_imported": 2
}

{
  "count": 1,
  "errors": [
    {
      "error": "ValidationError",
      "resource": "data",
      "description": "Too many users, at most 200 can be sent per call"
    }
  ]
}

Asynchronous upsert

This endpoint does not apply your payload during the request: it stores it and creates an import that applies it in the background. The response gives you the import_id of that import, and the number of items your request contained.

{
  "import_id": "QfejsQZ6mpOVHT5Tt1SdNLPZ",
  "objects_imported": 2
}

A 200 therefore means the import was created, not the payload was applied. To know how it went, fetch the import with the Fetch import route until its status is finished, then read its error flag:

error: false — every item of your payload has been upserted.
error: true — read title in data_tables_details[].error to know what happened. ValidationError means the payload was refused and nothing was upserted, description listing the invalid items. PartialFailure means part of it was applied: description counts the items that reported an issue, and parsing_error_details names the skipped ones — the most recent 100 — each with its line_number, row and details.

Imports of a company run one after the other, so an import can stay scheduled for a while when another one is already running. A 400 is still returned during the request itself, for a malformed body or a payload above the limit — in that case no import is created.

Merging successive calls with `debounce`

A payload above the limit of 200 has to be split across several calls, and each call would otherwise create its own import — all queued behind one another. Pass debounce, a number of seconds, to hold the import open: every call to the same endpoint made during that window joins the same import instead of queuing a new one, and they all return the same import_id. The window is opened by the first call, and a later call joins it without pushing its start further. Each payload keeps its own validation. A refused payload upserts nothing, but the payloads merged beside it are still applied — the import then reports the reason of every refusal in data_tables_details[].error. Only calls to the same endpoint are merged: users, manager attributions and group attributions always get their own import. This is deliberate, since attributions need the users they reference to exist already — send your users first, wait for their import to finish, then send the attributions.

Behavior

Transaction: If one group attribution is not parsable, none of the attributions of your call are upserted and the import finishes in error. You have to fix your payload and send it to us again. And if the import finishes without error, it means that every group attribution you sent us have been upserted. This all-or-nothing applies to the payload of your own call: when several calls share an import through debounce, a refused payload does not prevent the others from being applied
Conflict Rule and upsert: Be careful, each user can only have one group by dimension for a given period. Given new attributions dates will override conflicting dates already present in Qobra. Also, if you send a payload with two groups attributions for the same user over the same period the import is refused.
Limit: you can’t update more than 200 group attributions at a time.
Error behavior: In case of any error, your group attributions wont be upserted

Authorizations

X-API-Key

string

header

required

Query Parameters

debounce

integer

default:0

Optional (minimum: 0): debounce is the number of seconds we wait before starting the import. Every call to this endpoint made during that window joins the same import instead of queuing a new one, and they all return the same import_id. Use it when a payload above the limit of 200 has to be split across several calls. Only calls to this same endpoint are merged: users, manager attributions and group attributions always get their own import.

Body

application/json

The body contains the user data necessary to create a new user in Qobra

data

GroupAttributionPutBodyModel · object[]

required

Show child attributes

Response

Import created

The upsert is performed as a background import: the response identifies the import you just created, not the upserted objects. Fetch the import to know how it went.

import_id

string<ObjectId>

required

unique identifier of the import you created

objects_imported

integer

required

number of items your request contained

Inbound data integrations

Outbound data integrations

Public API Documentation

Authentication

Upsert group attributions bulk

Asynchronous upsert

Merging successive calls with `debounce`

Behavior

Authorizations

Query Parameters

Body

Response

​Asynchronous upsert

​Merging successive calls with debounce

​Behavior

Authorizations

Query Parameters

Body

Response

Asynchronous upsert

Merging successive calls with `debounce`

Behavior