Direct naar de inhoud
Sursa Developers

POST/v1/users/import

Gebruikers importeren uit CSV

users_import

Stuur een CSV-bestand in het veld csv. De eerste rij is de kopregel. Het scheidingsteken is , of ; en wordt uit de kopregel afgeleid. De codering is UTF-8 (een BOM is toegestaan), met maximaal 1000 gegevensrijen.
Kolommen: email (verplicht; aliassen e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; alias роль), groups (группы; scheid meerdere groepen met | of ;, op sleutel of op naam van een gewone groep), profile (data_profile, профиль; de sleutel van het dataprofiel). Onbekende kolommen worden overgeslagen en vermeld in ignored_columns.

Met dry_run: true (standaard) geeft het een voorbeeld zonder wijzigingen terug: de actie en de fouten per rij. Anders worden de rijen zonder fouten uitgevoerd:
- invite: verstuurt een uitnodiging met de rol, het profiel en de naam uit het bestand. Als e-mail is ingesteld, wordt er een e-mail verstuurd, en de link wordt in de response teruggegeven.
- exists: er bestaat al een gebruiker met dit e-mailadres. De gebruiker wordt aan de groepen uit het bestand toegevoegd; de rol en het profiel veranderen niet.
- pending: er wacht al een uitnodiging voor dit adres op acceptatie. De groepen uit het bestand worden eraan toegevoegd.

Rijen met fouten worden overgeslagen. Uitgenodigde gebruikers worden lid van hun groepen wanneer ze de uitnodiging accepteren. create_groups maakt ontbrekende gewone groepen aan; zonder deze optie is een onbekende groep een fout in de rij. De gebruikerslimiet van het abonnement en de gebruikersplaatsen van het cloudabonnement worden voor alle nieuwe uitnodigingen tegelijk gecontroleerd: als ze niet volstaan, wordt er niets uitgevoerd (402). De limiet op handmatige uitnodigingen (50 openstaande) geldt niet voor imports. Vereist het recht ORG_MANAGE_USERS. Schrijft het event users.import naar het auditlog, en invitation.create voor elke uitnodiging.

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Headerparameters

  • Idempotency-Keystring

    Sleutel om een schrijfactie veilig opnieuw te proberen: 1 tot 255 afdrukbare ASCII-tekens; een UUID v4 per logische bewerking wordt aanbevolen. Een nieuwe poging met dezelfde sleutel binnen 24 uur voert de bewerking niet opnieuw uit: Sursa geeft de opgeslagen response terug (status, headers en body) met de header Idempotency-Replayed: true. Dezelfde sleutel met een andere methode, een ander pad, een andere Content-Type of een andere body geeft 409 api.idempotency_mismatch; zolang het eerste request nog loopt, 409 api.idempotency_in_progress met Retry-After: 1. Na een 5xx- of 429-response wordt de sleutel vrijgegeven en voert een nieuwe poging de bewerking opnieuw uit. De sleutel geldt per organisatie en per aanroeper (API-sleutel, gebruiker of bronsleutel).

    length ≥ 1, length ≤ 255

Request-body

application/json

Object: UsersImportRequest

  • csvstringverplicht

    Inhoud van het CSV-bestand in UTF-8.

    length ≥ 1, length ≤ 2000000

  • dry_runboolean

    Alleen een voorbeeld (standaard). false voert de rijen zonder fouten uit.

    Standaard: true

  • default_rolestring

    Rol voor rijen zonder kolom role of met een lege cel.

    Standaard: "viewer"

  • default_profilestring | null

    Dataprofiel voor rijen zonder profiel. Is het leeg, dan wordt het standaardprofiel van de organisatie gebruikt (beheerders krijgen volledige toegang).

  • create_groupsboolean

    Ontbrekende gewone groepen aanmaken. Zonder deze vlag is een onbekende groep een fout in de rij.

    Standaard: false

  • ttl_daysinteger

    Geldigheid van de uitnodigingen in dagen.

    Standaard: 7≥ 1, ≤ 30

Responses

200Voorbeeld of resultaat van de import, rij voor rij

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

  • Idempotency-Replayed

    true: de response is opnieuw afgespeeld uit de opgeslagen response voor deze Idempotency-Key; de bewerking is niet opnieuw uitgevoerd.

application/json

Object: UsersImportResult

  • dry_runbooleanverplicht
  • totalintegerverplicht

    Aantal gegevensrijen in het bestand.

  • countsUsersImportCountsverplicht
  • delimiterstringverplicht

    Scheidingsteken, herkend aan de kopregel.

  • columnsarray of stringverplicht

    Herkende kolommen in canonieke vorm (email, name, role, groups, profile).

  • ignored_columnsarray of stringverplicht
  • created_groupsarray of stringverplicht

    Groepen die tijdens de uitvoering zijn aangemaakt.

  • limitUsersImportLimitverplicht
  • rowsarray of UsersImportRowverplicht
400Het request is ongeldig: een parameterwaarde of de toestand van het object staat de actie niet toe (`detail` is een melding).

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

402De organisatie heeft een abonnementslimiet bereikt (kaarten, opslag of gebruikers). `error.details` bevat `kind`, `limit` en `used`.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

413De request-body overschrijdt de toegestane grootte.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

422Validatiefout: de body of de parameters komen niet overeen met het schema (`detail` is een lijst met validatiefouten), of een parameterwaarde valt buiten het bereik (`detail` is een melding).

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

  • Retry-After

    Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← users · API-referentie