Skip to content

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.
1020No idp can be found based on the specified information
1072No identity can be found based on the specified information
1062The Username and Password IdP cannot be coupled through the couple API. Use the set Password API for that
1052Provided 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
/api/import/persons
Request header
"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" : "[email protected]"
      } ],
      "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 : "[email protected]"		 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