Profiles¶

Register a new User¶

username, email, first_name Are required fields. username may contain alphanumeric, _, @, +, . and - characters

POST /api/v1/profiles

Example¶

{
    "username": "demo",
    "first_name": "Demo",
    "last_name": "User",
    "email": "demo@localhost.com",
    "city": "Kisumu",
    "country": "KE",
    ...
}

List User Profiles¶

GET /api/v1/profiles

Example¶

curl -X GET https://api.ona.io/api/v1/profiles

To retrieve a specific list of user profiles, an authenicated user should use users query param whose value should be a comma-separated list of usernames as seen in the example below. A couple of things to note:

Anonymous users will get an empty result.
Authenticated users without the users query param will get their own profiles.

Example¶

curl -X GET https://api.ona.io/api/v1/profiles?users=alice,bob,charlene

Response¶

[
    {
        "url": "https://api.ona.io/api/v1/profiles/demo",
        "username": "demo",
        "first_name": "Demo",
        "last_name": "User",
        "email": "demo@localhost.com",
        "city": "",
        "country": "",
        "organization": "",
        "website": "",
        "twitter": "",
        "gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
        "require_auth": false,
        "user": "https://api.ona.io/api/v1/users/demo",
        "metadata": {},
        "joined_on": "2014-11-10T14:22:20.394Z"
    },
    ...
]

Retrieve User Profile Information¶

GET /api/v1/profiles/{username}

GET /api/v1/profiles/{pk}

Example¶

curl -X GET https://api.ona.io/api/v1/profiles/demo

Response¶

{
    "url": "https://api.ona.io/api/v1/profiles/demo",
    "username": "demo",
    "first_name": "Demo",
    "last_name": "User",
    "email": "demo@localhost.com",
    "city": "",
    "country": "",
    "organization": "",
    "website": "",
    "twitter": "",
    "gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
    "require_auth": false,
    "user": "https://api.ona.io/api/v1/users/demo",
    "metadata": {},
    "joined_on": "2014-11-10T14:22:20.394Z"
}

Partial updates of User Profile Information¶

Properties of the UserProfile can be updated using PATCH http method. Payload required is for properties that are to be changed in JSON, for example, {"country": "KE"} will set the country to KE.

PATCH /api/v1/profiles/{username}

Example¶

curl -X PATCH -d ‘{"country": "KE"}’ https://api.ona.io/api/v1/profiles/demo -H "Content-Type: application/json"

Response¶

{
    "url": "https://api.ona.io/api/v1/profiles/demo",
    "username": "demo",
    "first_name": "Demo",
    "last_name": "User",
    "email": "demo@localhost.com",
    "city": "",
    "country": "KE",
    "organization": "",
    "website": "",
    "twitter": "",
    "gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
    "require_auth": false,
    "user": "https://api.ona.io/api/v1/users/demo",
    "metadata": {},
    "joined_on": "2014-11-10T14:22:20.394Z"
}

Partial update for email requires password confirmation¶

Example¶

curl -X PATCH -d ‘{"email": "updated@email.com", "password": "password"}’ https://api.ona.io/api/v1/profiles/demo -H "Content-Type: application/json"

Partial update of the metadata profile property¶

This functionality allows for the updating of a key/value object of the metadata property without overwriting the whole metadata property. For example, if a user’s metadata was {"metadata": {"a": "Aaah", "b": "Baah"}} and we only wanted to update b with value Beeh, we would use this endpoing and add an overwrite param with value false.

PATCH /api/v1/profiles/{username}

Example¶

curl -X PATCH -d ‘{"metadata": {"b": "Beeh"}, "overwrite": "false"}’ https://api.ona.io/api/v1/profiles/demo -H "Content-Type: application/json"

Response¶

{
    "url": "https://api.ona.io/api/v1/profiles/demo",
    "username": "demo",
    "first_name": "Demo",
    "last_name": "User",
    "email": "demo@localhost.com",
    "city": "",
    "country": "KE",
    "organization": "",
    "website": "",
    "twitter": "",
    "gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
    "require_auth": false,
    "user": "https://api.ona.io/api/v1/users/demo"
    "metadata": {"a": "Aaah", "b": "Beeh"},
    "joined_on": "2014-11-10T14:22:20.394Z"
}

Change authenticated user’s password¶

Example¶

curl -X POST -d current_password=password1 -d new_password=password2 https://api.ona.io/api/v1/profile/demouser/change_password

Response¶

{
    "username": "demouser",
    "access_token": "30557df81ac63729d2865e90f334a5d00fe5e57c",
    "temp_token": "0c6a9f167c7074c781f635fe30cb60efa2473317"
}

Get the total number of monthly submissions¶

This gets the total number of submissions made in a month to a specific user’s forms. The result is a count of the submissions to both private and public forms.

If there are no private forms then only the number of submissions to the public forms is returned, and vice versa. If there are no submissions, then an empty dictionary is returned.

Use the month and year as query parameters to get the total number of submissions for a specific month. If no query parameters are used, the result is the number of submissions of the current month. If only month is used, then the year is assumed to be the current year. And if only year is passed, then the month is assumed to be the current year.

Example¶

curl -X GET https://api.ona.io/api/v1/profiles/demouser/monthly_submissions

Response¶

{
    "public": 41,
    "private": 185
}

Example¶

curl -X GET https://api.ona.io/api/v1/profiles/demouser/monthly_submissions?month=5&year=2018

Response¶

{
    "public": 240
}

Email verification¶

By default the email verification functionality is disabled. To enable this feature, set ENABLE_EMAIL_VERIFICATION in your settings file to True. VERIFIED_KEY_TEXT should also be set to ALREADY_ACTIVATED. If you have a custom verification url that you would prefer to be use instead of the default verification url, set it in VERIFICATION_URL settings variable. The verification url will be appended with the verificaiton key as query param. Once ENABLE_EMAIL_VERIFICATION has been set, a verification email will be sent when a new user is registered using the user profiles endpoint. The email verification endpoint expects verification_key query param as well as an optional redirect_url query param.

verification_key - A REQUIRED query param which is a hexadecimal associated with a user that expires after 1 day. The expiration day limit can be changed by resetting the ACCOUNT_ACTIVATION_DAYS settings variable.
redirect_url - An OPTIONAL query param that contains the url to redirect to when the verification_key has successfully been verified

Example¶

curl -X GET https://api.ona.io/api/v1/profiles/verify_email?verification_key=abc&redirect_url=https://red.ir.ect

Successful Response¶

A succesful response or redirect includes 2 values:

username - the account username of the verified email
is_email_verified - the status of the verified email. It will be True for a successful response

if there is a redirect url, 2 query params will be appended to the url

<redirect-url>?username=johndoe&is_email_verified=true

If there isn’t a redirect url, the response will be

{
    'username': 'johndoe',
    'is_email_verified': 'true'
}

Failed Response¶

Missing or invalid verification key

Send verification email¶

To send a verification email, for example when a user has changed his/her email address, the user making the request should authenticate and provide username - which should be the same as the user making the request - in the post data. The requesting user can also provide redirect_url as part of the post data. The redirect_url will be appended as query param to the verification url and used to redirect the user to that url once the verification_key has successfully been verified.

Example¶

curl -X POST -d username=johndoe -d redirect_url="https://red.ir.ect" https://api.ona.io/api/v1/profiles/send_verification_email

Successful Response¶

Verification email has been sent

Failed Response¶

Verification email has NOT been sent