POST/v1/users/import

Importera användare från CSV

users_import

Skicka en CSV-fil i fältet csv. Den första raden är rubrikraden. Avgränsaren är , eller ; och identifieras från rubrikraden. Kodningen är UTF-8 (en BOM är tillåten), med upp till 1000 datarader.
Kolumner: email (obligatorisk; alias e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; alias роль), groups (группы; skilj flera grupper åt med | eller ;, efter nyckel eller namn på en vanlig grupp), profile (data_profile, профиль; dataprofilens nyckel). Okända kolumner hoppas över och listas i ignored_columns.

Med dry_run: true (standard) returneras en förhandsvisning utan ändringar: åtgärden och felen för varje rad. Annars genomförs raderna utan fel:
- invite: skickar en inbjudan med rollen, profilen och namnet från filen. Ett e-postmeddelande skickas om e-post är konfigurerad, och länken returneras i svaret.
- exists: en användare med den här e-postadressen finns redan. Användaren läggs till i grupperna från filen; rollen och profilen ändras inte.
- pending: en inbjudan till den här adressen väntar redan på att accepteras. Grupperna från filen läggs till i den.

Rader med fel hoppas över. Inbjudna användare går med i sina grupper när de accepterar inbjudan. create_groups skapar saknade vanliga grupper; utan det är en okänd grupp ett radfel. Prisplanens gräns för användare och abonnemangets användarplatser kontrolleras för alla nya inbjudningar på en gång: om de inte räcker genomförs ingenting (402). Gränsen för manuella inbjudningar (50 väntande) gäller inte för importer. Kräver behörigheten ORG_MANAGE_USERS. Skriver händelsen users.import till granskningsloggen och invitation.create för varje inbjudan.

Autentisering

Skicka en API-nyckel i huvudet Authorization: Authorization: Bearer <nyckel>.

Parametrar i huvuden

Idempotency-Keystring
Nyckel för ett säkert nytt försök med en skrivning: 1–255 utskrivbara ASCII-tecken; ett UUID v4 per logisk åtgärd rekommenderas. Ett nytt försök med samma nyckel inom 24 timmar kör inte åtgärden igen, utan returnerar det sparade svaret (status, huvuden och brödtext) med huvudet Idempotency-Replayed: true. Samma nyckel med en annan metod, sökväg, Content-Type eller brödtext returnerar 409 api.idempotency_mismatch; medan det första anropet fortfarande pågår returneras 409 api.idempotency_in_progress med Retry-After: 1. Efter ett 5xx- eller 429-svar frigörs nyckeln, och ett nytt försök kör åtgärden igen. Nyckeln gäller inom organisationen och för anroparen (API-nyckel, användare eller källnyckel för en egen källa).
length ≥ 1, length ≤ 255

Anropets brödtext

application/json

Objekt: UsersImportRequest

csvstringobligatorisk
CSV-filens innehåll i UTF-8.
length ≥ 1, length ≤ 2000000
dry_runboolean
Bara förhandsvisning (standard). false utför raderna utan fel.
Standard: true
default_rolestring
Roll för rader utan kolumnen role eller med en tom cell.
Standard: "viewer"
default_profilestring | null
Dataprofil för rader utan profil. Om den är tom används organisationens standardprofil (administratörer får full åtkomst).
create_groupsboolean
Skapa vanliga grupper som saknas. Utan den här flaggan är en okänd grupp ett radfel.
Standard: false
ttl_daysinteger
Inbjudningarnas giltighet i dagar.
Standard: 7≥ 1, ≤ 30

Svar

200Förhandsvisning eller resultat av importen, rad för rad

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.
Idempotency-Replayed
true betyder att svaret spelades upp från det sparade svaret för denna Idempotency-Key: åtgärden kördes inte igen.

application/json

Objekt: UsersImportResult

dry_runbooleanobligatorisk
totalintegerobligatorisk
Antal datarader i filen.
countsUsersImportCountsobligatorisk
delimiterstringobligatorisk
Avgränsare som identifierades från rubrikraden.
columnsarray of stringobligatorisk
Igenkända kolumner i kanonisk form (email, name, role, groups, profile).
ignored_columnsarray of stringobligatorisk
created_groupsarray of stringobligatorisk
Grupper som skapades under körningen.
limitUsersImportLimitobligatorisk
rowsarray of UsersImportRowobligatorisk

400Anropet är ogiltigt: ett parametervärde eller objektets tillstånd tillåter inte åtgärden (`detail` är ett meddelande).

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

401Inga autentiseringsuppgifter skickades (varken en sessionscookie eller en API-nyckel), eller så hittades inte nyckeln.

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

402Organisationen har nått en gräns i sin prisplan (kort, lagring eller användare). `error.details` innehåller `kind`, `limit` och `used`.

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

403Åtgärden är inte tillåten: rollen räcker inte, det saknas åtkomst till samlingen eller kortet, anropet körs i läget ”View as” (visa som en annan användare), eller organisationen är avstängd eller borttagen (`detail` är ett objekt med `code: org_suspended | org_deleted`).

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

413Anropets brödtext överskrider den tillåtna storleken.

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

422Valideringsfel: brödtexten eller parametrarna stämmer inte med schemat (`detail` är en lista med valideringsfel), eller så ligger ett parametervärde utanför det tillåtna intervallet (`detail` är ett meddelande).

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

429För många anrop (`api.rate_limited`), organisationens kvot för minuten, dygnet eller månaden är förbrukad (`api.quota_exceeded`; `error.details` innehåller `quota`, `limit` och `reset_at`), organisationens gräns är nådd eller svarstjänsten är upptagen (`answers.engine_busy`). Vänta den tid som anges i huvudet `Retry-After`.

Svarshuvuden

Retry-After
Antal sekunder att vänta innan du skickar anropet igen.
RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

Felkoder

Koder som den här slutpunkten kan returnera i error.code, utöver de allmänna koderna för alla anrop.

Säkra nya försök

Skicka huvudet Idempotency-Key (till exempel ett UUID) med varje POST och PATCH. Ett nytt försök med samma nyckel inom 24 timmar returnerar det sparade svaret i stället för att köra anropet igen.

Hastighetsbegränsningar

Svaren innehåller huvudena RateLimit och RateLimit-Policy samt de tidigare X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset. Ett 429-svar har Retry-After i sekunder: vänta och försök igen.

← users · API-referens

curl -X POST 'https://api.sursa.com/v1/users/import' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"csv":"string"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prova

API-nyckel

Nyckeln finns bara i den här flikens minne och skickas bara till https://api.sursa.com.

Anropen påverkar din organisations riktiga data.

Idempotency-Key header

Idempotency-Key

Är fältet tomt skapas en ny nyckel för varje anrop.

Anropets brödtext (JSON)