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¶

1	`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:

Code	Description
1018	The specified email address is not a valid email address
1027	Primary email is missing.
8102	Unable to couple account with INVITED status to username and password identity provider.
8103	It is impossible to import accounts in INACTIVE status.
8104	Unknown error while importing account.
8105	Import failed with referenced error. Please check logs for more details by providing reference if of this error.
8106	Person id is required. Please add it to the request and retry the operation.
1020	No idp can be found based on the specified information
1072	No identity can be found based on the specified information
1062	The Username and Password IdP cannot be coupled through the couple API. Use the set Password API for that
1052	Provided external person's identity is already coupled with another account

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	Persons required	Persons to import.	ImportPersonsRequest

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¶

1	`/api/import/persons`

Request header¶

1	`"string"`

Request body¶

{
  "persons" : [ {
    "profile" : {
      "reference_id" : "989b4e21-9553-4e00-a8cd-b6fd04579503",
      "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" : {
      "digest" : "Ydn5lkpvdIJEXhp5DRx8v+t9ZlM=",
      "salt" : "tA7mKvUnYGw=",
      "nr_of_iterations" : 64000
    },
    "step_up" : {
      "totp" : {
        "secret_key" : "JBSWY3DPEHPK3PXP"
      }
    },
    "status" : "ACTIVATED",
    "identities" : {
      "idp_id" : "75d89885-629e-4f54-b719-39b0598339d8",
      "external_person_id" : "12345-12345-12345-12345"
    }
  } ]
}

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

ExternalPersonId¶

Name	Description	Schema
external_person_id optional	Identifier of external IDP that should be coupled with Onegini IDP Example : `"12345-12345-12345-12345"`	string
idp_id optional	Idp id that should be coupled with account. This can be obtained using Identity Providers Config API Example : `"75d89885-629e-4f54-b719-39b0598339d8"`	string (uuid)

Gender¶

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

Type : enum (M, F, U)

HashedPassword¶

Name	Description	Schema
digest required	Base64 encoded digest (hash) for a password. Example : `"Ydn5lkpvdIJEXhp5DRx8v+t9ZlM="`	string
nr_of_iterations required	Number of times the given hash algorithm is executed to generate the digest. Example : `64000`	integer
salt required	Base64 encoded salt used to generate the digest. Example : `"tA7mKvUnYGw="`	string

Identifier¶

Type : string (uuid)

ImportPerson¶

Name	Description	Schema
hashed_password optional	Example : `"[hashedpassword](#hashedpassword)"`	HashedPassword
identities optional	Example : `"[externalpersonid](#externalpersonid)"`	ExternalPersonId
profile required	Example : `"[profile](#profile)"`	Profile
status required	Imported person status Example : `"ACTIVATED"`	string
step_up optional	Example : `"[stepup](#stepup)"`	StepUp

ImportPersonsRequest¶

Name	Description	Schema
persons required	Example : `[ "[importperson](#importperson)" ]`	< ImportPerson > array

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
reference_id required	Unique identifier for account (UUID) Example : `"989b4e21-9553-4e00-a8cd-b6fd04579503"`	string

StepUp¶

Name	Description	Schema
totp optional	Example : `"[timebasedonetimepassword](#timebasedonetimepassword)"`	TimeBasedOneTimePassword

TimeBasedOneTimePassword¶

Name	Description	Schema
secret_key required	base32 encoded binary secret key used for calculation Example : `"JBSWY3DPEHPK3PXP"`	string

Security¶

basic_auth¶

Type : basic