Creating Orders

This central method is used to create any kind of new order for identifications and/or qualified electronic signatures for natural persons.

Special considerations for eSigning

Signature Type

You can choose between using AES (Advanced Electronic Signature) or QES (Qualified Electronic Signature) when creating an order to sign documents. When creating orders, QES will be used by default.

To be able to use AES for signing, you need to go through a special on-boarding process in which a special seal will be created that will later be used to create AES'. Please contact IDnow for that.

Multi-Signing

When requesting multiple parties to sign a document, please make sure, that each person uses a distinct mobile number. If the phone number is shared among two or more parties, the signing process will fail predictably.

Please also inform your customers about that restriction.

Requirements

The requested products must be associated with and enabled on your account by IDnow.

Method and URL

[PUT] https://customer.identity.tm/api/2.10/putOrder

JSON Request Body

Element	Parent	Type	Len	Req	Description
Ref	[ROOT]	S	100	N	Your internal reference number to the order. This field can be used to associate the order with an ID in your system and has no meaning for IDnow except in the case of a Testrobot (see Additional Functions).
Product	[ROOT]	N		Y	Specifies the product you want to use. 12 Identification via any of the enabled methods including Video, but excluding autoID 13 eID – Online-Ausweisfunktion (eID PIN, available for German documents only) 15 eSign 16 Identification via autoID 17 Mobile phone number verification 19 Reader
Add	[ROOT]	N		Y	Specifies additional product behaviors. 0 will be the correct choice in most cases. 0 Normal behavior 1 eID: only request eidRestrictedIdentifier 4 eSign Order 128 Use AES instead of QES for eSign 256 Use SES instead of QES for eSign 512 Click to Sign per signature box (SES only) 1024 Click to Sign with single button, no signature boxes shown (SES only) 4096 License Check (with ID) 8192 License Check (without ID) 131072 Record Video 4194304 PoS eSign service 8388608 PoS identification service
Lang	[ROOT]	S	2	N	Language hint for video system, has no effect on web or app flow. Use ISO 639-1 language codes.
eIDSettings	[ROOT]	O		N	Settings for eID, no effect if user selects different method
VerifyMobileNumber	eIDSettings	B		N	Enables mobile phone number verification
EnableOCR	eIDSettings	B		N	Enables OCR to gather document number, issuing authority and date of issue of identification document.
CaptureImages	eIDSettings	B		N	Capture images of the legitimation document; if EnableOCR is set, images will always be taken
NoVideoFallback	eIDSettings	B		N	If eID fails, no fallback to Video will be offered.
DisableEID	eIDSettings	B		N	Disable eID
getTargetLink	[ROOT]	B		N	Set to true to get the TargetURL in response (otherwise only the user will be informed via e-mail)
getVideoHashes	[ROOT]	B		N	Set to true to get the video system hash in the response if Product is 12 or 15.
getDeepLink	[ROOT]	B		N	If set to true, a deeplink for mobile application will be part of the response
RedirectURL	[ROOT]	O		N
Success	RedirectURL	S	150	N	Redirect to URL after success
Abort	RedirectURL	S	150	N	Redirect to URL after failure
WebhookURL	[ROOT]	O		N
AfterVideo	WebhookURL	S	250	N	Webhook to trigger when the user leaves the video system. Cannot be used together with AfterIdent. Ident data will not necessarily be ready when triggered.
AfterIdent	WebhookURL	S	250	N	Webhook to trigger when the identification has been conducted. Cannot be used together with AfterVideo. Ident data will not necessarily be ready when triggered.
OnFinal	WebhookURL	S	250	N	Webhook to trigger when the order has been finally processed
OnError	WebhookURL	S	250	N	Webhook to trigger when a partner is unable to process an order (does not apply to video)
OnVideoError	WebhookURL	S	250	N	Webhook to trigger when a temporary error occurs while performing a video identification
OnStatusChange	WebhookURL	S	250	N	Special webhook to trigger on when order reaches a specific status (configurable on account level)
Phone	[ROOT]	PN	50	N	Phone number of your customer
Mobile	[ROOT]	PN	50	N	Mobile number of your customer
Email	[ROOT]	S	50	Y	Email address of your customer
Address	[ROOT]	O		Y	Mandatory if user is allowed to use product Shop
Firstname	Address	S	50	Y	Physical Address data of your customer (Contact / Location)
Surname	Address	S	50	Y
CompanyName	Address	S	50	N
Street	Address	S	50	N
ZipCode	Address	S	5	N
City	Address	S	100	N
Country	Address	S	3	Y	The ISO-Code of the country (ISO 3166) e.g. DE, AT, NL
IdentData	[ROOT]	O		N	The fields you provide, will be checked. Empty fields will be picked if possible.
Firstname	IdentData	S	50	Dep	Please give us notice if you plan to omit any of these fields.
Surname	IdentData	S	50	Dep
Street	IdentData	S	100	Dep
ZipCode	IdentData	S	5	Dep
City	IdentData	S	100	Dep
Country	IdentData	S	2	Dep	The ISO-Code of the country (ISO 3166) e.g. DE, AT, NL
Birthdate	IdentData	DS		Dep	Date of birth
Birthplace	IdentData	S	100	Dep	Place of birth
Birthname	IdentData	S	75	N	Surname at birth. Will only be determined if field is neither null nor omitted
Nationality	IdentData	S	50	Dep	Nationality
Title	IdentData	S	50	Dep	Title
Artistname	IdentData	S	50	Dep	Artist name/alias
Gender	IdentData	S		Dep	female/male/diverse
Email	IdentData	S	50	N	Email address of your customer
Mobile	IdentData	PN	50	N	Mobile number of your customer
CollectedBy	IdentData	S	255	Dep	Identifier who carried out the identification, PoS eSign Service only
IDCard	IdentData	O		No	Data about the ID document
CardNo	IDCard	S	50	Dep	ID document number
PlaceOfIssue	IDCard	S	100	Dep	ID document place of issue
DateOfIssue	IDCard	DS		Dep	ID document date of issue
CountryOfIssue	IDCard	S	3	Dep	The ISO-Code of the issuing country (ISO 3166) e.g., DE, AT, NL
ValidUntil	IDCard	DS		Dep	ID document valid until
Images	IDCard	O		Dep
Front	Images	S		Dep	Base64 encoded JPEG image of the front side of ID Card
Back	Images	S		Dep	Base64 encoded JPEG image of the front side of ID Card
DriverLicence	IdentData	O		Dep	If Driver's License Check with Add 4096 and/or 8192, provide data if available
LicenceNo	DriverLicence	S	50	Dep
Classes	DriverLicence	S	50	Dep
CountryOfIssue	DriverLicence	S	3	Dep	The ISO-Code of the issuing country (ISO 3166) e.g., DE, AT, NL
DateOfIssue	DriverLicence	DS		Dep	Date of issue
ValidUntil	DriverLicence	DS		Dep	Date until the license is valid
Additional	IdentData	O		N	If you need special attributes, you can add here for Shop up to 2, Video up to 10 items. <detail> can have a length of 50
<detail>	Additional	O		N
Type	<detail>	N		Y	Data type of the field. Required for additional fields. 1 String 2 Date 3 Boolean 4 Country code according to ISO 3166
Label	<detail>	S	100	Y	Readable label for the element
Value	<detail>	S	150	N	Initial field value
LegitimationDocument	[ROOT]	A		N	Individual legitimation documents in case defaults are not sufficient
Document	LegitimationDocument	A	50		The readable description shown to the agent / employee processing the order
eSignPDF	[ROOT]	O/A		N	Document(s) designated for signing, use array for multiple documents.
Data	eSignPDF	S		N	Base64 encoded PDF (PDF must be unprotected). Supported PDF versions: 1.3 to 1.7 and 2.0
Filename	eSignPDF	S	50	N	Filename
SignaturePosX	eSignPDF	N		N	The units are PDF Points equivalent to 1/72 inch. The lower/left corner of the document is the origin X=0 and Y=0. Position and field name cannot be used at the same time.
SignaturePosY	eSignPDF	N		N
SignatureHeight	eSignPDF	N		N	Only applicable if SignaturePos is also set. The units are PDF Points equivalent to 1/72 inch.
SignatureWidth	eSignPDF	N		N
SignaturePage	eSignPDF	N		N	Page to place the signature on
SignatureFieldName	eSignPDF	S		N	Use the given predefined signature field in the PDF. Position and field name cannot be used at the same time.
SignatureTag	eSignPDF	S		N	A tag (text), that is used to define the position of the signature (alterative to X/Y coordinates). It must only apear once in the document, otherwise an error will be returned.
SignatureOffsetPosX	eSignPDF	I		N	Can be used with SignatureTag
SignatureOffsetPosY	eSignPDF	I		N	Can be used with SignatureTag
Stamping	eSignPDF	A		N	Array of objects, used to place additional stamps on the document. This feature is only available when using Namirial TSP.
Page	Stamping	N		Dep	Page to place stamp on. Default is 1.
PosX	Stamping	N		Dep	Position of the stamp on the page. The units are PDF Points equivalent to 1/72 inch. Default is 100;100.
PosY	Stamping	N		Dep
Tag	Stamping	S		N	A tag (text), that is used to define the position of stamps (alterative to X/Y coordinates). Stamp will be placed at each occurrence of matching text in the document.
OffsetPosX	eSignPDF	I		N	Can be used with Tag
OffsetPosY	eSignPDF	I		N	Can be used with Tag
Width	Stamping	N		N	Size of the stamp. The units are PDF Points equivalent to 1/72 inch. Default is 200;60.
Height	Stamping	N		N
Content	Stamping	S	500	Dep	String content of the stamp, available placeholders are: [DATE] Date of signature [TIME] Time of signature [DT] Date and time of signature [SIGNEE] Name of signee
eSignHash	[ROOT]	O/A		N
Hash	eSignHash	S		N	Base64 Hash of prepared PDF
Filename	eSignHash	S	50	N	Filename
eSignOptions	[ROOT]	O
AdditionalCheckboxes	eSignOptions	A	300		Text for Checkboxes in the esign workflow that must be checked before signing is possible (Array of String(s))
MultiSignOptions	[ROOT]	O		N
FirstOrderID	MultiSignOptions	S	14		To reference an eSign order to the master. Contract from first Order will be signed by each.
SignParameters	MultiSignOptions	O/A		N	Signature parameters for file(s) given with the first order
Filename	SignParameters	S	50	N	Filename given with first order
SignaturePosX	SignParameters	N		N	The units are PDF Points equivalent to 1/72 inch. The lower/left corner of the document is the origin X=0 and Y=0. Default is 100;100.
SignaturePosY	SignParameters	N		N
SignatureWidth	SignParameters	N		N	Only applicable if SignaturePos is also set. The units are PDF Points equivalent to 1/72 inch. Default is 200;60.
SignatureHeight	SignParameters	N		N
SignaturePage	SignParameters	N		N	Page to place the signature on. Default is 1.
SignatureFieldName	SignParameters	S		N	Use the given predefined signature field in the PDF
IdentDataSigned	[ROOT]	S		N	Previously generated identification data for signing purposes
EmailNotifications	[ROOT]	O		N	Send final processing mails, overrides customer settings
OnPositiveIdent	EmailNotifications	S	150	N	Send a mail to this address in case of a final positive status
OnNegativeIdent	EmailNotifications	S	150	N	Send a mail to this address in case of a final negative status
OnTimeOut	EmailNotifications	S	150	N	Send a mail to this address in case of a final timeout status
OnLeave	EmailNotifications	S	150	N	Send a mail to this address in case the user leaves the identification process
Purpose	[ROOT]	S/O	150	N	Purpose of the identification that will be reported in the app to the end user. If a string is given here, it will be used for every language. In case language dependent strings are required, provide an object here and see the next line.
<lang>	Purpose	S	150	N	The key (<lang>) must be an ISO 3166-1 Alpha-2 language code, the value is the desired purpose text
eSignTanSmsText	[ROOT]	S		N	eSign TAN Text, only for eSign orders. Use [TAN] as a placeholder for the TAN.
verificationSmsText	[ROOT]	S		N	Mobile number verification SMS text. Use [TAN] as a placeholder for the TAN.
CustomerRouteTag	[ROOT]	S	250	Dep	Used to route orders to other preconfigured account(s), for example for invoicing purposes.
Autotest	[ROOT]	S	50	N	Used to activate testrobot flow (see Additional Functions).

Response Data

Element	Parent	Type	Len	Occ	Description
OrderID	[ROOT]	S	20	Y	Our internal ID of the Order, always unique
Ref	[ROOT]	S	100	Y	Your internal ID of the Order, can be set multiple times
TargetURL	[ROOT]	S	100	Dep	URL to redirect your customer
DeepLinkURL	[ROOT]	S	100	Dep	App DeepLink URL
AutoIdURL	[ROOT]	S	100	Dep	URL to autoID Web
SignedDataAccepted	[ROOT]	B		Dep	In case signed ident data has been provided, this flag will indicate if the data has been accepted
VideoHashes	[ROOT]	O		Dep	Video system reference data
ShortCode	VideoHashes	S	5	Dep	Reference number to start Video identification in identity App on iOS/Android
LongCode	VideoHashes	S	20	Dep	Reference number for identity Video SDK
UserID	[ROOT]	N		Dep	ID used for Shop user login, only provided in case this is an agent onboarding order
UserToken	[ROOT]	S	32	Dep	Token used for Shop user login, only provided in case this is an agent onboarding order
Error	[ROOT]	S		Dep	Error message in case an error occurred

HTTP Codes

202 Order accepted, JSON document in body

400 Bad request, error description in body

401 Authentication failed, please check username and password

Example Request

{
  "Ref": "Sign-me_Account_Creation_Test",
  "Product": 15,
  "Add": 8,
  "getTargetLink": true,
  "getDeepLink": true,
  "getVideoHashes": true,
  "WebhookURL": {
    "OnFinal": "https://webhook.site/1234567_890?OnFinal=%5BOrderID%5D"
  },
  "RedirectURL": {
    "Success": "https://www.example.com/redirect/positive?OrderID=[OrderID]",
    "Abort": "https://www.example.com/redirect/negative?OrderID=%5BOrderID%5D"
  },
  "Email": "e.mustermann@example.com ",
  "Mobile": "+491711234567",
  "Address": {
    "Firstname": "Erika",
    "Surname": "Mustermann",
    "Street": "Heidestr. 17",
    "ZipCode": "43000",
    "City": "Köln",
    "Country": "DE"
  },
  "IdentData": {
    "Firstname": "Erika",
    "Surname": "Mustermann",
    "Street": "Heidestr. 17",
    "ZipCode": "43000",
    "City": "Köln",
    "Birthdate": "1964-08-12",
    "Birthplace": "Berlin",
    "Additional": {
      "idCardDateOfIssue": {
        "Type": 2,
        "Label": "Date of Issue",
        "Value": "2010-01-11"
      }
    }
  }
}

Example Response

{
  "OrderID": "99921269855041",
  "Ref": "Sign-me_Account_Creation_Test",
  "TargetURL": "https://www.identity.tm/status/37C4B60A72A1C6C74FC038282CED500B",
  "DeepLinkURL": "https://www.identity.tm/ident/37C4B60A72A1C6C74FC038282CED500B",
  "VideoHashes": {
    "ShortCode": "SHU8T",
    "LongCode": "a9PPz-eFcNBifsk--bNJ"
  }
}