Import API

Overview

This document describes the API for importing accounts to Onegini IDP.

Supported operations:

  • importing status and profile
  • coupling with username and password identity provider
  • importing accounts in status CREATED, INVITED, ACTIVATED and BLOCKED

Unsupported operations:

  • importing accounts in status INACTIVE
  • coupling accounts in status INVITED with username and password

Version information

Version : 1.0.0

Paths

Import accounts

POST /api/import/persons

Description

Import accounts with specific status, profile and possibility to couple with username and password identity provider. As a result it returns list of accouns that have been imported with success (successful_reference_ids) or additionally list of accounts that couldn't have been imported (failures).

Failures contains additional information that gives possibility to verify what went wrong.

List of possible errors returned in response:

CodeDescription
1018The specified email address is not a valid email address
1027Primary email is missing.
8102Unable to couple account with INVITED status to username and password identity provider.
8103It is impossible to import accounts in INACTIVE status.
8104Unknown error while importing account.
8105Import failed with referenced error. Please check logs for more details by providing reference if of this error.
8106Person id is required. Please add it to the request and retry the operation.

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Body Profile
required
Person's to create profile. ImportPersonRequest

Responses

HTTP Code Description Schema
201 All of the accounts have been imported. PersonsImportResult
207 Some of the accounts haven't been imported. Check response for details. PersonsImportResult
503 Import API feature is disabled ErrorResponse

Consumes

  • application/json

Tags

  • import

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/import/persons
Request header
"string"
Request body
{
  "profile" : {
    "gender" : "M",
    "name" : {
      "first_name" : "John William",
      "last_name" : "Doe",
      "initials" : "J.W.D",
      "display_name" : "Mr John W. Doe, Msc."
    },
    "date_of_birth" : "1995-05-24",
    "email_addresses" : [ {
      "primary" : true,
      "verified" : false,
      "value" : "john.doe@onegini.com"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true,
      "value" : "+31 654 321 098"
    } ],
    "addresses" : [ {
      "house_number" : 9,
      "house_number_addition" : "2nd floor, 101",
      "street_name" : "Main street",
      "city" : "Woerden",
      "postal_code" : "1000 AA, 12345-6789",
      "region" : "Utrecht",
      "country_code" : "NL",
      "company_name" : "Onegini",
      "attentation" : "John Doe",
      "primary" : true
    } ],
    "custom_attributes" : [ {
      "name" : "myCRM",
      "value" : "ABC123456"
    } ],
    "preferred_locale" : "en_US"
  },
  "hashed_password" : {
    "username" : "foo@example.org",
    "password" : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
    "encryption_parameter" : "BVLdWx//evkFUt1bH/96+Q=="
  },
  "status" : "ACTIVATED"
}

Example HTTP response

Response 201
{
  "successful_reference_ids" : [ "08f831ab-a22f-4159-a851-15eec46c3717" ],
  "failures" : [ {
    "error_code" : 1001,
    "error_message" : "Requested feature is currently not available"
  } ]
}
Response 207
{
  "successful_reference_ids" : [ "08f831ab-a22f-4159-a851-15eec46c3717" ],
  "failures" : [ {
    "error_code" : 1001,
    "error_message" : "Requested feature is currently not available"
  } ]
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "Import API is currently not available"
  }
}

Definitions

Address

Name Description Schema
attentation
optional
'To attention of' field
Example : "John Doe"
string
city
optional
Name of the city
Example : "Woerden"
string
company_name
optional
Name of the company
Example : "Onegini"
string
country_code
optional
Country code
Example : "NL"
string
house_number
optional
Numeric part of the house number
Example : 9
integer
house_number_addition
optional
Any addition that further clarifies the house number
Example : "2nd floor, 101"
string
postal_code
optional
Postal code
Example : "1000 AA, 12345-6789"
string
primary
optional
Flag to indicate whether this is the primary person's address
Example : true
boolean
region
optional
Name of the region, province or state
Example : "Utrecht"
string
street_name
optional
Name of the street
Example : "Main street"
string

CustomAttribute

Name Description Schema
name
optional
Attribute name
Example : "myCRM"
string
value
optional
Attribute value
Example : "ABC123456"
string

EmailAddress

Name Description Schema
primary
optional
Flag to indicate whether this is the primary person's email address
Example : true
boolean
value
optional
Email address value
Example : "john.doe@onegini.com"
string (email)
verified
optional
An optional flag to indicate whether this email address has been verified
Example : false
boolean

ErrorResponse

Name Description Schema
error_code
optional
Example : 1001 integer (int32)
error_message
optional
Example : "Requested feature is currently not available" string

Gender

The gender of the person. Possible values: M (male), F (female), U (undefined)

Type : enum (M, F, U)

HashedPassword

Name Description Schema
encryption_parameter
required
Initialization vector used by encryption algorithm
Example : "BVLdWx//evkFUt1bH/96+Q=="
string
password
required
User password [encrypted]
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string
username
required
Username
Example : "foo@example.org"
string

Identifier

Type : string (uuid)

ImportPersonRequest

Name Description Schema
hashed_password
optional
Example : "[hashedpassword](#hashedpassword)" HashedPassword
profile
required
Example : "[profile](#profile)" Profile
status
required
Imported person status
Example : "ACTIVATED"
string

Name

Name Description Schema
display_name
optional
Displayed name, e.g. Mr John W. Doe, MSc. If no displayName is specified, firstName + lastName is returned
Example : "Mr John W. Doe, Msc."
string
first_name
optional
Person first name(s)
Example : "John William"
string
initials
optional
Person initials
Example : "J.W.D"
string
last_name
optional
Person last name
Example : "Doe"
string

PersonsImportResult

Name Description Schema
failures
optional
Accounts that failed to import
Example : [ "[errorresponse](#errorresponse)" ]
< ErrorResponse > array
successful_reference_ids
optional
Person ids that were successfully imported
Example : [ "[identifier](#identifier)" ]
< Identifier > array

PhoneNumber

Name Description Schema
primary
optional
Flag to indicate whether this is the primary person's phone number
Example : true
boolean
value
optional
Phone number value
Example : "+31 654 321 098"
string (email)
verified
optional
An optional flag to indicate whether this phone number has been verified
Example : true
boolean

Profile

Name Description Schema
addresses
optional
Collection of person's (postal) addresses, can be empty
Example : [ "[address](#address)" ]
< Address > array
custom_attributes
optional
Collection of person's custom attributes, can be empty
Example : [ "[customattribute](#customattribute)" ]
< CustomAttribute > array
date_of_birth
optional
Timezone independent representation of a birth date
Example : "1995-05-24"
string
email_addresses
required
Collection of person's email addresses. Profile must contain at least one email address attribute
Example : [ "[emailaddress](#emailaddress)" ]
< EmailAddress > array
gender
optional
Example : "[gender](#gender)" Gender
name
optional
Example : "[name](#name)" Name
phone_numbers
optional
Collection of person's phone numbers, can be empty
Example : [ "[phonenumber](#phonenumber)" ]
< PhoneNumber > array
preferred_locale
optional
Preferred locale
Example : "en_US"
string

Security

basic_auth

Type : basic