Ctrlk
Help CenterContact Support

User

API for managing users, including creation, lookup, and blocking.

Lookup a user by Referral Code

get

Looks up a user based upon their referralCode and returns their personal information. This method is useful for retrieving the user when only the Referral Code is available.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

Query parameters
referralCodestringRequired

The referralCode of the user you want to retrieve.

Example: BOBTESTERSON
Responses
200

User found

application/json

A user in the impact.com referral program.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
lastInitialstringOptional

The first initial of the user's last name.

Example: T
emailstring · emailOptional

The user's email address.

Example: [email protected]
emailHashstringOptional

An MD5 hash of the user's email address.

Example: 714ed06b2d5c95b93d499a3be731c19f
imageUrlstringOptional

URL of the user's profile image. Empty string if not set.

referralCodestringOptional

The user's primary referral code.

Example: CFMVQHNUEU2AWWDO
cookieIdstring · nullableOptional

The cookie ID associated with this user.

Example: abc123cookie
paymentProviderIdstring · nullableOptional

The ID of the user in the payment provider system.

Example: pay_abc123
localestring · nullableOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestring · nullableOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referralSourcestring · nullableOptional

The source of the user's referral.

Example: DIRECT
firstSeenIPstring · nullableOptional

The IP address the user was first seen from.

Example: 203.0.113.42
lastSeenIPstring · nullableOptional

The IP address the user was last seen from.

Example: 203.0.113.42
dateCreatedinteger · int64Optional

Unix timestamp (milliseconds) when the user was created.

Example: 1774386824964
dateBlockedinteger · int64 · nullableOptional

Unix timestamp (milliseconds) when the user was blocked. Null if not blocked.

Example: 1779871222634
get
/{tenant_alias}/user
cURL

Create or Update a User

post

This method creates or updates a User object by performing an atomic upsert operation. This method will not create or update the Account linked by accountId.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

Body

Request body for creating or updating a user.

idstringRequired

The unique identifier for the user.

Example: abc123
accountIdstringRequired

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
emailstring · emailOptional

The user's email address.

Example: [email protected]
localestringOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestringOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referralCodestringOptional

A custom referral code to assign to the user.

Example: BOBTESTERSON
Responses
200

User Created or Updated

application/json

A user in the impact.com referral program.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
lastInitialstringOptional

The first initial of the user's last name.

Example: T
emailstring · emailOptional

The user's email address.

Example: [email protected]
emailHashstringOptional

An MD5 hash of the user's email address.

Example: 714ed06b2d5c95b93d499a3be731c19f
imageUrlstringOptional

URL of the user's profile image. Empty string if not set.

referralCodestringOptional

The user's primary referral code.

Example: CFMVQHNUEU2AWWDO
cookieIdstring · nullableOptional

The cookie ID associated with this user.

Example: abc123cookie
paymentProviderIdstring · nullableOptional

The ID of the user in the payment provider system.

Example: pay_abc123
localestring · nullableOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestring · nullableOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referralSourcestring · nullableOptional

The source of the user's referral.

Example: DIRECT
firstSeenIPstring · nullableOptional

The IP address the user was first seen from.

Example: 203.0.113.42
lastSeenIPstring · nullableOptional

The IP address the user was last seen from.

Example: 203.0.113.42
dateCreatedinteger · int64Optional

Unix timestamp (milliseconds) when the user was created.

Example: 1774386824964
dateBlockedinteger · int64 · nullableOptional

Unix timestamp (milliseconds) when the user was blocked. Null if not blocked.

Example: 1779871222634
post
/{tenant_alias}/user
cURL
200

User Created or Updated

Lookup a user

get

Looks up a user based upon their id and returns their personal information. This method just returns the details of the user in question, and not all associated properties like Rewards, Balances, or Referrals.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Responses
200

User found

application/json

A user in the impact.com referral program.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
lastInitialstringOptional

The first initial of the user's last name.

Example: T
emailstring · emailOptional

The user's email address.

Example: [email protected]
emailHashstringOptional

An MD5 hash of the user's email address.

Example: 714ed06b2d5c95b93d499a3be731c19f
imageUrlstringOptional

URL of the user's profile image. Empty string if not set.

referralCodestringOptional

The user's primary referral code.

Example: CFMVQHNUEU2AWWDO
cookieIdstring · nullableOptional

The cookie ID associated with this user.

Example: abc123cookie
paymentProviderIdstring · nullableOptional

The ID of the user in the payment provider system.

Example: pay_abc123
localestring · nullableOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestring · nullableOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referralSourcestring · nullableOptional

The source of the user's referral.

Example: DIRECT
firstSeenIPstring · nullableOptional

The IP address the user was first seen from.

Example: 203.0.113.42
lastSeenIPstring · nullableOptional

The IP address the user was last seen from.

Example: 203.0.113.42
dateCreatedinteger · int64Optional

Unix timestamp (milliseconds) when the user was created.

Example: 1774386824964
dateBlockedinteger · int64 · nullableOptional

Unix timestamp (milliseconds) when the user was blocked. Null if not blocked.

Example: 1779871222634
get
/{tenant_alias}/account/{accountId}/user/{userId}
cURL

Lookup a user PII

get

Returns details of the personally identifiable information stored in the impact.com system for a specific user.

🚧 Warning! This method should only be used in connection with data protection and privacy compliance.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Responses
200

User found

application/json

Full personally identifiable information for a user, including rewards, referrals, and share links. Only use in connection with data protection and privacy compliance.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
lastInitialstringOptional

The first initial of the user's last name.

Example: T
emailstring · emailOptional

The user's email address.

Example: [email protected]
emailHashstringOptional

An MD5 hash of the user's email address.

Example: 714ed06b2d5c95b93d499a3be731c19f
imageUrlstringOptional

URL of the user's profile image.

cookieIdstring · nullableOptional

The cookie ID associated with this user.

Example: abc123cookie
paymentProviderIdstring · nullableOptional

The ID of the user in the payment provider system.

Example: pay_abc123
localestring · nullableOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestring · nullableOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referablebooleanOptional

Whether this user can be referred by another user.

Example: true
referralSourcestring · nullableOptional

The source of the user's referral.

Example: UNKNOWN
firstSeenIPstring · nullableOptional

The IP address the user was first seen from.

Example: 203.0.113.42
lastSeenIPstring · nullableOptional

The IP address the user was last seen from.

Example: 203.0.113.42
firstSeenIPLocationstring · nullableOptional

The geographic location derived from firstSeenIP.

Example: San Francisco, CA, US
lastSeenIPLocationstring · nullableOptional

The geographic location derived from lastSeenIP.

Example: San Francisco, CA, US
firstSeenUserAgentstring · nullableOptional

The browser user agent string from the user's first session.

Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
lastSeenUserAgentstring · nullableOptional

The browser user agent string from the user's most recent session.

Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
dateCreatedinteger · int64Optional

Unix timestamp (milliseconds) when the user was created.

Example: 1774386824964
referredByCodesstring[]Optional

Referral codes used to refer this user.

Example: ["NCC8IQ4ADTVDQAOA"]
segmentsstring[]Optional

The segments this user belongs to.

get
/{tenant_alias}/account/{accountId}/user/{userId}/pii
cURL

Block user

post

Block a user from making successful referrals based upon their user and account id.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Responses
200

User blocked successfully

application/json
objectOptional
post
/{tenant_alias}/account/{accountId}/user/{userId}/block
cURL

Unblock user

post

Unblock a user based upon their user and account id.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Responses
200

User unblocked successfully

application/json
objectOptional
post
/{tenant_alias}/account/{accountId}/user/{userId}/unblock
cURL

List users

get

List all of the users in your Advocate referral programs. This method supports pagination and search queries.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

Query parameters
querystringOptional

A search query that can be used to filter users by email, name or ID.

limitintegerOptional

A limit on the number of results returned.

Default: 10
offsetintegerOptional

When included, offsets the first result returned in the list.

Default: 0
Responses
200

Users found

application/json
countintegerOptional
totalCountintegerOptional
get
/{tenant_alias}/users
cURL
200

Users found

Lookup a user (Open Endpoint)

get

This method looks up a user based on their id and returns their personal information including sharelinks. This endpoint requires authentication via a write token or API credentials.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Query parameters
fieldsstringOptional

The fields to be included in the response. Cannot coexist with extraFields.

extraFieldsstringOptional

The fields to be included in the response in addition to all the default fields. Cannot coexist with fields.

Responses
200

User found

application/json

A user object returned by open endpoints. Includes program share links and custom fields.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
emailstring · emailOptional

The user's email address.

Example: [email protected]
imageUrlstringOptional

URL of the user's profile image.

cookieIdstring · nullableOptional

The cookie ID associated with this user.

Example: abc123cookie
localestring · nullableOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestring · nullableOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referablebooleanOptional

Whether this user can be referred by another user.

Example: true
firstSeenIPstring · nullableOptional

The IP address the user was first seen from.

Example: 203.0.113.42
lastSeenIPstring · nullableOptional

The IP address the user was last seen from.

Example: 203.0.113.42
dateCreatedinteger · int64Optional

Unix timestamp (milliseconds) when the user was created.

Example: 1774386824964
segmentsstring[]Optional

The segments this user belongs to.

referredByCodesstring[]Optional

Referral codes used to refer this user.

Example: ["NCC8IQ4ADTVDQAOA"]
get
/{tenant_alias}/open/account/{accountId}/user/{userId}
cURL

Create a user and account (Open Endpoint)

post

This method creates a user and an account and returns the user object representing that newly created user/account. Because this call creates a user, it requires either a write token or an API key.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Query parameters
fieldsstringOptional

The fields to be included in the response. Cannot coexist with extraFields.

extraFieldsstringOptional

The fields to be included in the response in addition to all the default fields. Cannot coexist with fields.

Body

An object describing an individual user submitted to an open endpoint when you want to create or update a user.

idstringRequired

The unique identifier provided for this user. Use the user's email as their user Id.

Example: [email protected]
accountIdstringRequired

The unique identifier of the account. Value must match id. Use the user's email as their account Id.

Example: [email protected]
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
emailstring · emailOptional

The email address provided for the user.

Example: [email protected]
referablebooleanOptional

Flag to determine whether a user is able to be referred.

localestringOptional

The user's locale, used for Internationalization (e.g., en_US).

Example: en_US
countryCodestringOptional

The user's ISO 3166-1 Alpha-2 country code (e.g., US).

Example: US
dateUsTaxFormSubmittedinteger · int64Optional

The timestamp of when a user's W-9 tax form was submitted.

referredByCodesstring[]Optional

An array of referral codes used to refer this account.

cookiesstringOptional

The Base64URL encoded attribution cookie values.

Example: eyJjb29raWVJZCI6ImFiYzEyMyJ9
segmentsstring[]Optional

A list of operations for adding and removing a user from segments (e.g., ["segment1", "~segment2"]).

Responses
post
/{tenant_alias}/open/account/{accountId}/user/{userId}
cURL

User Upsert (Open Endpoint)

put

This method updates/creates a user and an account and returns the user object representing that newly created user/account. Because this call creates a user, it requires either a write token or an API key.

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Query parameters
fieldsstringOptional

The fields to be included in the response. Cannot coexist with extraFields.

extraFieldsstringOptional

The fields to be included in the response in addition to all the default fields. Cannot coexist with fields.

Body

An object describing an individual user submitted to an open endpoint when you want to create or update a user.

idstringRequired

The unique identifier provided for this user. Use the user's email as their user Id.

Example: [email protected]
accountIdstringRequired

The unique identifier of the account. Value must match id. Use the user's email as their account Id.

Example: [email protected]
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
emailstring · emailOptional

The email address provided for the user.

Example: [email protected]
referablebooleanOptional

Flag to determine whether a user is able to be referred.

localestringOptional

The user's locale, used for Internationalization (e.g., en_US).

Example: en_US
countryCodestringOptional

The user's ISO 3166-1 Alpha-2 country code (e.g., US).

Example: US
dateUsTaxFormSubmittedinteger · int64Optional

The timestamp of when a user's W-9 tax form was submitted.

referredByCodesstring[]Optional

An array of referral codes used to refer this account.

cookiesstringOptional

The Base64URL encoded attribution cookie values.

Example: eyJjb29raWVJZCI6ImFiYzEyMyJ9
segmentsstring[]Optional

A list of operations for adding and removing a user from segments (e.g., ["segment1", "~segment2"]).

Responses
200

Information about the upserted user

application/json

A user object returned by open endpoints. Includes program share links and custom fields.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastNamestringOptional

The user's last name.

Example: Testerson
emailstring · emailOptional

The user's email address.

Example: [email protected]
imageUrlstringOptional

URL of the user's profile image.

cookieIdstring · nullableOptional

The cookie ID associated with this user.

Example: abc123cookie
localestring · nullableOptional

The user's locale (e.g. en_US).

Example: en_US
countryCodestring · nullableOptional

The user's ISO 3166-1 Alpha-2 country code (e.g. US).

Example: US
referablebooleanOptional

Whether this user can be referred by another user.

Example: true
firstSeenIPstring · nullableOptional

The IP address the user was first seen from.

Example: 203.0.113.42
lastSeenIPstring · nullableOptional

The IP address the user was last seen from.

Example: 203.0.113.42
dateCreatedinteger · int64Optional

Unix timestamp (milliseconds) when the user was created.

Example: 1774386824964
segmentsstring[]Optional

The segments this user belongs to.

referredByCodesstring[]Optional

Referral codes used to refer this user.

Example: ["NCC8IQ4ADTVDQAOA"]
put
/{tenant_alias}/open/account/{accountId}/user/{userId}
cURL

Delete a user (Open Endpoint)

delete

Delete a user in your impact.com project. By default this endpoint only deletes a User on an Account (and not the Account itself).

Authorizations
AuthorizationstringRequired

Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

accountIdstringRequired

The ID of the account.

userIdstringRequired

The ID of the user.

Query parameters
doNotTrackbooleanOptional

Do not track this user (this user cannot be re-registered on the same account).

preserveEmptyAccountbooleanOptional

Do not delete accounts when all the users in the account are deleted.

Responses
delete
/{tenant_alias}/open/account/{accountId}/user/{userId}
cURL
No content

Get a user by a referral code (Open Endpoint)

get

Looks up a user based upon their ReferralCode and returns their personal information. This is an Open Endpoint and disabled by default.

Path parameters
tenant_aliasstringRequired

Tenant being referenced. E.g. "aboih12h16t"

Query parameters
referralCodestringRequired

The code with which to lookup the user.

Responses
200

Found user

application/json

Minimal user information returned when looking up a user by referral code from the open endpoint.

idstringOptional

The unique identifier for the user.

Example: abc123
accountIdstringOptional

The unique identifier of the account the user belongs to.

Example: abc123
firstNamestringOptional

The user's first name.

Example: Bob
lastInitialstringOptional

The first initial of the user's last name.

Example: T
referralCodestringOptional

The user's primary referral code.

Example: CFMVQHNUEU2AWWDO
imageUrlstringOptional

URL of the user's profile image.

get
/{tenant_alias}/open/user
cURL
PreviousUser OverviewNextModels

Last updated