Skip to main content

Create a user by external reference

POST 
/api/users/by-reference

Requires admin token. Create a user in the Ownli System identified only by the partner's remote-system id (externalReference). Email, phone, address and policy are all optional. Users are identified by externalReference within your partner account.

Request​

Query Parameters

    returnExistingUserIfExists boolean

    Return the user object if a user matching externalReference exists in your partner account. Default behavior is to return an error.

    Example: true

Body

required

    externalReference stringrequired

    Possible values: Value must match regular expression ^[A-Za-z0-9._:+@\-/]{1,128}$

    The user's id in the partner's remote/login system. May be an email address. Up to 128 characters; letters, digits and . _ : - / + @ . This is the only required field. (Required)

    firstName string

    User's First Name. (Optional)

    lastName string

    User's Last Name. (Optional)

    email string

    User's Email. (Optional)

    isEmailVerified boolean

    Has the user's email been verified by the partner?

    phone string

    Cell Phone Number in the E.164 format +15556667777. (Optional)

    isPhoneVerified boolean

    Has the user's phone been verified by the partner?

    customField1 string

    Custom Field 1

    customField2 string

    Custom Field 2

    customField3 string

    Custom Field 3

    customField4 string

    Custom Field 4

    customField5 string

    Custom Field 5

    address

    object

    Address

    addressLine1 string

    Street Address

    addressLine2 string
    city string

    City

    state stringrequired

    2 Letter State Code (eg. AL, CA, CO etc.

    country string

    2 Letter Country Code. Must be US.

    zip string

    Zipcode

    policyAddress

    object

    Address

    addressLine1 string

    Street Address

    addressLine2 string
    city string

    City

    state stringrequired

    2 Letter State Code (eg. AL, CA, CO etc.

    country string

    2 Letter Country Code. Must be US.

    zip string

    Zipcode

    additionalDrivers

    object[]

    Possible values: <= 10

    Additional drivers for the user (max 10). Only firstName and lastName are required. Ignored when an existing user is returned (returnExistingUserIfExists); use /api/users/{userId}/drivers to change them.

  • Array [

    • middleName string

    Possible values: <= 100 characters

    Driver's middle name.

    dateOfBirth string

    Date of birth as yyyy-MM-dd.

    gender string

    Possible values: <= 100 characters

    Gender, free text (e.g. Male, Female, Non-binary).

    maritalStatus string

    Possible values: <= 100 characters

    Marital status, free text (e.g. Single, Married).

    relationshipToInsured string

    Possible values: <= 100 characters

    Relationship to the primary insured, free text (e.g. Spouse, Child).

    driversLicense string

    Possible values: <= 50 characters

    Driver's license number.

    driversLicenseState string

    2 letter code of the state that issued the license.

    education string

    Possible values: <= 100 characters

    Education, free text.

    occupation string

    Possible values: <= 100 characters

    Occupation, free text.

    firstName stringrequired

    Possible values: <= 100 characters

    Driver's first name. (Required)

    lastName stringrequired

    Possible values: <= 100 characters

    Driver's last name. (Required)

  • ]

    • policyInfo

    object

    Policy

    policyNumber stringrequired

    Policy Number

    startDate string

    [startDate] The start date of the policy. ISO8601 UTC format YYY-MM-DDThh:mm:ss.SSSZ (e.g. 2024-01-01T00:00:00.000Z). Required unless caller is in policy.dates-optional.partner-ids.

    endDate string

    [endDate] The end date of the policy. ISO8601 UTC format YYY-MM-DDThh:mm:ss.SSSZ (e.g. 2024-01-01T00:00:00.000Z). Required unless caller is in policy.dates-optional.partner-ids.

Responses​

The created user object.

Schema

    id string

    Unique Id for the user

    firstName string

    User's first name

    lastName string

    User's last name

    email string

    User's email address

    phone string

    User's cell phone number

    adminNote string

    Internal admin note

    externalReference string

    The user's id in the partner's remote/login system, if the user was created via the external-reference endpoint. Null otherwise.

    customField1 string

    Custom Field 1

    customField2 string

    Custom Field 2

    customField3 string

    Custom Field 3

    customField4 string

    Custom Field 4

    customField5 string

    Custom Field 5

    address

    object

    addressLine1 string

    Street Address Line 1

    addressLine2 string

    Street Address Line 2

    city string

    City

    state string

    2 Letter State Code

    country string

    2 Letter Country Code

    zip string

    Zip

    policyAddress

    object

    addressLine1 string

    Street Address Line 1

    addressLine2 string

    Street Address Line 2

    city string

    City

    state string

    2 Letter State Code

    country string

    2 Letter Country Code

    zip string

    Zip

    additionalDrivers

    object[]

    Additional drivers, in the order they were added. Single-user endpoints: always a list, empty ([]) if the user has none. User lists: always null (not loaded); fetch the user by id to get them.

  • Array [

    • id string

    Driver id. Use it with PUT/DELETE /api/users/{userId}/drivers/{driverId}.

    firstName string

    First name

    middleName string

    Middle name

    lastName string

    Last name

    dateOfBirth string

    Date of birth, yyyy-MM-dd

    gender string

    Gender

    maritalStatus string

    Marital status

    relationshipToInsured string

    Relationship to the primary insured

    driversLicense string

    Driver's license number

    driversLicenseState string

    2 letter code of the state that issued the license

    education string

    Education

    occupation string

    Occupation

  • ]

    • policyInfo

    object

    Policy

    policyNumber string

    Policy Number

    startDate string

    Start Date

    endDate string

    End Date

    tosAnswer string

    Possible values: [None, Accepted, Declined]

    User's answer to terms of service for sharing data with Partner. (Only valid for certain partners)

    partnerCode string

    A code generated for the user to share with Partner. (Only valid for certain partners)

    dateRegistered string

    Time at which user was registered on the system

    updated string

    Last updated timestamp

    emailVerified boolean
    phoneVerified boolean
    fraud boolean
Loading...