Users

The user object

Attribute

Type

Description

id

uuid

The unique identifier for the user.

first_name

string

The first name of the user.

last_name

string

The last name of the user.

full_name

string

The full name of the user.

username

string

The username of the user.

country

string

Two letter ISO 3166-1 alpha-2 country code representing the country the user is located in.

timezone

string

The name of timezone where the user is located.

timezone_utc_offset

integer

The hours to or from UTC of the timezone where the user is located.

verified

boolean

Whether the user has a verified account.

official

boolean

Whether the user's account has been marked as an official one.

preferences

string

A JSON object which stores the user's preferences.

meta

string

A JSON object which can store meta data used by the client.

image

Image

An optional user image.

relationships

array

An array of Relationship objects describing the relationship between the user and the current user.

Example

{
"id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"first_name": "John",
"last_name": "Dough",
"full_name": "John Dough",
"username": "jondough",
"country": "UK",
"timezone": "Europe/London",
"timezone_utc_offset": 0,
"verified": true,
"official": true,
"preferences": "{\"color\": \"green\"}",
"meta": "",
"image": {
"id": "75cc21be-fe47-4702-74bc-07b84beed5fb",
"url": "https://{imagehost}/ui/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"full_screen_url": "https://{imagehost}/full/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"thumbnail_url": "https://{imagehost}/users/moments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"created_at": "2017-09-04T12:26:43.403883Z",
"updated_at": "2017-09-04T12:26:43.403883Z"
},
"relationships": [
{
"id": "4ec5c820-520d-4668-ba84-0d7bdee23af5",
"contact_id": "a5d8ecf0-0002-4294-8d36-c0336d3bef35",
"type": "contact",
"created_at": "2017-04-19T14:35:09.308904Z",
"updated_at": "2017-04-19T14:35:09.308904Z"
}
]
}

The current user object

Attribute

Type

Description

id

uuid

The unique identifier for the user.

status

string

The status of the user. created

active

locked

rejected

pending

first_name

string

The first name of the user.

last_name

string

The last name of the user.

full_name

string

The full name of the user.

username

string

The username of the user.

country

string

Two letter ISO 3166-1 alpha-2 country code representing the country the user is located in.

timezone

string

The name of timezone where the user is located.

timezone_utc_offset

integer

The hours to or from UTC of the timezone where the user is located.

locale

string

The preferred locale selected by the user.

verified

boolean

Whether the user has a verified account.

official

boolean

Whether the user's account has been marked as an official one.

email

string

The verified email address for the user.

unverified_email

string

The new/updated email address, until it is verified by the user.

date_of_birth

time

An optional date of birth timestamp for the user.

phone

string

The verified phone number for the user.

unverified_phone

string

The new/updated phone number, until it is verified by the user.

preferences

string

A JSON object which stores the user's preferences.

token

string

The authentication token of the user. Only sent after creating the user at signup.

image

Image

An optional user image.

created_at

time

The time when the user was created.

updated_at

time

The time when the user was updated.

{
"id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"status": "active",
"first_name": "John",
"last_name": "Dough",
"full_name": "John Dough",
"username": "jondough",
"country": "UK",
"timezone": "Europe/London",
"timezone_utc_offset": 0,
"locale": "en-UK",
"verified": true,
"official": true,
"email": "[email protected]",
"date_of_birth": "1985-09-04T12:25:48.288511Z",
"phone": "+44 123 1234 1234",
"preferences": "{\"color\": \"green\"}",
"token": {
"id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
"status": "approved",
"token": "wxKj3JV6ET1dXVou77675tMqC...",
"error_code": "",
"error_message": "",
"expires_at": "2017-09-04T12:25:48.827724Z"
}
"image": {
"id": "75cc21be-fe47-4702-74bc-07b84beed5fb",
"url": "https://{imagehost}/ui/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"full_screen_url": "https://{imagehost}/full/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"thumbnail_url": "https://{imagehost}/users/moments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"created_at": "2017-09-04T12:26:43.403883Z",
"updated_at": "2017-09-04T12:26:43.403883Z"
},
"created_at": "2017-09-04T12:25:48.827724Z",
"updated_at": "2017-09-04T12:25:48.827724Z"
}

The relationship object

Attribute

Type

Description

id

uuid

The unique identifier for the relationship.

contact_id

uuid

The unique identifier for the contact.

type

string

The type of the relationship. blocked contact following friend guardian

created_at

time

The time when the relationship was created.

updated_at

time

The time when the relationship was updated.

User preferences

User preferences is a custom client-specific JSON object. However, there are a few system preferences available:

Key

Type

Description

appear_in_search

boolean

Set whether or not the user can be found be other users.

receive_direct_payment

boolean

Sets whether or not the user can receive payment directly. Even if true, user can still pay be paid via payment requests initiated by the user.

receive_requests

boolean

Sets whether or not the user can receive payment requests.

Get the current user

Get the currently logged in user. Returns a current user object.

Request
Response
Request

GET /v1/users/current

Response

200 OK

Returns a current user object.

Get a user

Get the public information for a specific user. Returns a user object. If the current has a relationship to this user, the user object will embed a relationship object.

Request
Response
Request

GET /v1/users/{id}

Response

200 OK

Returns a user object.

Block a user

Block a specific user.

Request
Response
Request

POST /v1/users/{id}/block

Response

200 OK

Unblock a user

Unblock a specific user.

Request
Response
Request

POST /v1/users/{id}/unblock

Response

200 OK

Get activity summary

Get a summary of events that occurred after the time defined by the start_at filter.

Request
Response
Request

GET /v1/users/current/summary

Attribute

Type

Operators

Values

start_at

time

gt

YYYY-MM-DD HH:MM:SS

Response

200 OK

Attribute

Type

Description

current.unpaid_requests

integer

The number of current unpaid payment requests.

since_last_time.payments_received

integer

The number of payments received during the defined period.

since_last_time.requests_received

integer

The number of payment requests received during the defined period.

{
"current": {
"unpaid_requests": 2,
},
"since_last_time": {
"payments_received": 3,
"requests_received": 2,
}
}

Search for users

Search for users based on one or all of the following: name, username, email, phone number.

Request
Response
Request

POST /v1/users/search

Attribute

Type

Description

name

array

A list of names.

username

array

A list of usernames.

email

array

A list of emails.

phone

array

A list of phone numbers.

show_current_friends

string

Show users that are already in the current user's contact list. default: false

{
"name": ["John Dough", "John Doe"],
"username": ["johndough", "johndoe"],
"email": ["[email protected]"],
"phone": ["+44 111 2222 3333"],
"show_current_friends": true
}
Response

200 OK

[
{
"id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"first_name": "John",
"last_name": "Dough",
"full_name": "John Dough",
"username": "jondough",
"country": "UK",
"timezone": "Europe/London",
"timezone_utc_offset": 0,
"verified": true,
"official": true,
"image": {
"id": "75cc21be-fe47-4702-74bc-07b84beed5fb",
"url": "https://{imagehost}/ui/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"full_screen_url": "https://{imagehost}/full/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"thumbnail_url": "https://{imagehost}/users/moments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"created_at": "2017-09-04T12:26:43.403883Z",
"updated_at": "2017-09-04T12:26:43.403883Z"
},
"relationships": [
{
"id": "4ec5c820-520d-4668-ba84-0d7bdee23af5",
"type": "contact",
"created_at": "2017-04-19T14:35:09.308904Z",
"updated_at": "2017-04-19T14:35:09.308904Z"
}
]
}
]

Create a user account (sign up)

Create a new user account.

Request
Response
Request

POST /v1/users

Attribute

Type

Description

first_name

string

The first name of the user. required

last_name

string

The last name of the user. required

username

string

The unique username of the user. required

email

string

The user's email address.

phone

string

The user's phone number.

pin

string

The user's PIN. required

referral_code

string

An optional referral code.

verifications

array

An array of verification IDs for specific user fields.

addresses

array

An array of addresses.

device

Device

The user device information. required

image

Image

The height of the device's screen.

{
"first_name": "John",
"last_name": "Dough",
"username": "johndough",
"email": "[email protected]",
"phone": "+44 123 1234 1234",
"pin": "1234",
"verifications": [
{
"field": "email",
"id": "fa42f949-349a-4d1b-829c-93e6d2daeac4"
},
{
"field": "phone",
"id": "c5c18397-2ed7-43c1-b481-a5f3d3a96ef1"
}
],
"addresses": [
{
"title": "Calista Wise",
"street_address": "7292 Dictum Av.",
"locality": "San Antonio",
"administrative_area": "MI",
"postal_code": "47096",
"country": "US",
"is_primary": true
}
],
"device": {
"id": "582a5abb-1335-4794-4855-11e067b8c55e",
"make": "iPhone",
"model": "iPhone6,2",
"os_name": "iOS",
"os_version": "8.0"
},
"image": {
"url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
}
}
Response

201 Created

Returns a current user object with an embedded token.

Updated the current user

Update the current user information.

Request
Response
Request

PUT /v1/users/current

Attribute

Type

Description

first_name

string

The first name of the user.

last_name

string

The last name of the user.

username

string

The unique username of the user.

email

string

The name of the OS running on the device.

phone

string

The version of the OS running on the device.

pin

string

The user's PIN.

device

Device

The user device information.

image

Image

The height of the device's screen.

Response

200 OK

Returns the current user object.