IntroductionReveal is the simplest way for developers to integrate avatar support into their apps and websites. Ovatar handles the uploading, storing, resizing and framing avatars along with handling and parsing of metadata and facial data points (such as age) along with many many other features.

Our powerful REST API that can be integrated into any project or platform with ease, but we have also build out custom libraries for iOS and Android to make it even easier to get avatars into your app.


There is not much more personal than a photo of a person, with this privacy is super important to us. With this ovatar puts the user first by giving them full control over their data. To achieve this we give control to you (the app owner) as well as to the user directly.

App Owner

the app owner (you or your team) has the ability to revoke or append any image uploaded by your application at any time with the 'ovatar' endpoint. Any custom integration of ovatar that does not allow the user to do this in their app will violate our terms of service and will have their application terminated.


the user will be notified of any uploaded photo of themselves via an email delivered to them. They will be able to append or revoke this upload at any time using the dashboard. In some cases, you may wish to update your own data when changes have been made by the user which is why we have webhook support.


All endpoints return by default a JSON object. This structure varies depending on the endpoint, but all calls DO return a error_code [integer] and a status [string] along with a HTTP Status Code.

Example JSON Response

    "status": "image not found",
    "error_code": 422
}] uses HTTPS by default, all requests should be made using the base url below


Currently, the endpoints available do not require any user authentication, this is subject to change in future versions.

But for each request, an AppKey is required. This app key will be used to identify who uploaded what and gives developers a sense of responsibility. Additionally, the AppKey will also be used to monitor and limit your requests, based on your chosen plan

To obtain an application key please register your interest here.

The app key should be passed in an HTTP Header oappkey, alternatively, this can be passed as a GET request using the parameter appkey

Additional HeadersReveal

As we are focused on giving the user full control the more information the better. We suggest sending the following headers to make it even clearer where the image came from.

odevice - send the device name, this could just be 'macbook' or more personalised 'steve's macbook'

oplatform - this is the platform used to make the request ie 'ios' or 'macos'


Bulk migration support is not supported... yet! However, when querying GET ovatar you can pass the original URL of the ovatar stored on your system as long as this URL is a valid image that complies with our upload specifications in terms of file types and file size.

Like with any uploaded ovatar you will be given a key which allows you to edit the picture at a later date and query as many times as you like without costing you any additional 'requests'.

Successfully migrated Ovatars will give a similar JSON returns to when using the conventional upload endpoint. See POST /upload for more information.

However, if you are querying the endpoint with a 'type' that does not return JSON object (an image for example) then this will return will not be given object for obvious reasons. This is why we highly recommend using webhooks as it is crucial you store the upload key. See webhooks for more information.

The original image will be copied to our repository meaning that you may delete any original copies if you wish. Unlike Instagram and similar services, we do not take ownership of this image. However, we do make it public thus assessable by other authorized apps. If you do not wish your user's images to be made public or do not agree to these terms please do not use this feature. If you do and wish to remove any migrated images please contact us


Ovatar allows you to query any image you have uploaded as many times as you like for free! This is done by passing an id when querying the GET /ovatar endpoint.

If you do not have an ovatar id then you can query a user ovatar by passing an email address or phone number via the query parameter. Each unique email address or phone number passed will count as 1 request. The number of requests per month is dependant on your current plan. This is renewed at the end the start of every month.

Accounts holders will be notified twice by email. Once when the account passes 80% usage, and again when the account passes 90% usage. Once the account reaches 100% usage for the month the endpoint will return a 403 error.

ErrorsReveal uses conventional HTTP response codes to indicate the success or failure of an API request. Unless specified otherwise, the endpoint will return a JSON response containing an error code as well as a status for more information about the response.

Code Information
200 Everything worked as expected.
400 Application Key was not sent or is invalid. Your app key is auto generated and can be found in the dashboard.
401 You do not have the privillages access, append or delete specific data.
403 The request limit has been exceeded for the current month.
404 The requested resource could not be found.
405 This request type is not allowed.
422 A parameter is missing or invalid.
500 Something went wrong on's end (Hopefully never)

OvatarGET /ovatarReveal

The 'Ovatar' endpoint is the primary endpoint for retrieving uploaded images and rich user, and image data. Content can be retrieved either by a valid phone number or email address or if you are the application owner you can query by id.

By default this data is returned in JSON format, however using the type parameter you can return a user image or placeholder if no image exists.

Querying by email address of phone number will by default check for uploads from your application. If there have been no prior uploads it will fall back to the latest image uploaded. Querying by key will always retrun the only the image from your application.

Each plan has unique request limit. This means you can query the same user unlimited times but each new request will be counted even if no data is returned.

Additional data will be returned depending on your application plan type. For example, if you have the 'premium' plan various EXIF, and added metadata will be returned along with metrics on the queried user. The data structure will also change depending on the application owner too.


Parameter Description
(string)query A valid email address or phone number with the country code (+44). This or the id parameter is required
(string)id The id value returned when you upload an image, this is perfered over using query. This or the query parameter is required
(string)type The data can be returned as a json object or as an image. By default image is selected
(string)placeholder Returned if an image could not be found

default will return an logo as an image.

404will return a 404 header with no body.

customwill return a custom image (which can be set in the dashboard).

jsonwill return a the same as 404 but will return a json object.

(string)size The size of the image retuned


medium(120px) is default


(string)migrate The original host URL of the avatar you wish to migrate to ovatar. See more about migration above.

JSON Response Example

    "status": "image returned",
    "error_code": 200,
    "output": {
      "application": {
        "name": "Ovatar",
        "url": "",
        "logo": "",
        "signup": "2019-02-15 22:04:42"
      "type": "user",
      "query": "",
      "timestamp": "2019-02-21 20:59:28",
      "public": true,
      "id": "a5bbs8j758tuib7mjxmlb34rrisasjt8",
      "captured": "2018:05:23 20:25:59",
      "device": "Joe's iPhone",
      "exif": {
        "fnumber": "12/5",
        "exposure": "1/20",
        "flash": "16",
        "camera_iso": "160",
        "make": "Apple",
        "device": "iPhone X",
        "software": "11.3",
        "gps": {
          "latitude": 9.7122083333333,
          "longitude": 99.987052777778
      "user": {
        "sex": 1,
        "name": "Joe Barbour",
        "email": "",
        "country": {
          "name": "United Kingdom",
          "code": 826
        "id": "sh7sDPPAd7shanosahsYYi7s61s"

OvatarDELETE /ovatarReveal

Along with being able to return image and other data, the ovatar endpoint also allows for the deletion of content that was uploaded by application, or the ability report content that was not uploaded by your application.


Parameter Description
(string)query A valid email address or phone number with the country code (+44). This or the id parameter is required
(string)id The id value returned when you upload an image, this is perfered over using query. This or the query parameter is required
(string)reason This is a short text-based summary as to why the image has been reported/removed. E.g 'This image contains nudity'.

UploadPOST /uploadReveal

Uploading new avatars to your application can be done via the upload endpoint. It requires a image and valid phone number and/or email address

It is suggested that you reduce a file size prior to uploading an image file to improve the response time, however it is not necessary. Nor is it required to resize or crop an image, this is all server side.

Ovatar only supports one image per user, per application. If you upload another image with the same application key, the original image will be overwritten.

The request will return a JSON body, and if sucsessful (200) this will return an id. This id must be stored in your records, without this key you will only be able to query the image using a email or phone number which will cost 'requests' (see above). Additionally the ovatar will be read only, meaning you cannot replace or remove the ovatar once uploaded.

POST data must be passed as a JSON object. Images should also be encoded to Base64. Unencoded data will be rejected by the server.



Parameter Description
(string)user A valid email address or phone number with the country code (+44), or both seporated with a pipe (|). This is required.
(base64)ovatar A PNG, GIF or JPG image encoded Base64 binary data
(string)fullname The users fullname eg Steve Jobs. Not required.
(string)id Required if an existing ovatar has been uploaded with the same appkey and same user (email address or phone number). Without this you will not have write permissions
(boolean)private If set to true the uploaded image will only accessed by only your application, not publically like it is by default. This option is available to those with an unlimited plan

JSON Response Example

  "status": "image uploaded",
  "error_code": 200,
  "output": {
    "phone": "+44810283847182",
    "email": "",
    "id": "PPwzdstk5g6873buot0a4ram02ljxao"

IP LookupGET /ipReveal

Our IP endpoint returns a wealth of information. This includes information about the ISP and the Client device (OS & Browser) as well as location data (county, state, and city), country restrictions and regulations, timezone and even currency. Furthermore, this endpoint can even return basic user information about Ovatar users registered at that IP address.

This endpoint and the Ovatar endpoint are designed to be used concurrently together to enrich your user/customer information. This is why they are packaged together in 1 plan.

Similar to the Ovatar endpoint each unique query is marked as 1 request. Depending on your plan. See the requests section (above) for more information.


Parameter Description
(string)query A valid IP address, this must not be a localhost IP such as
(string)types Allows you to specify which data types to be returned. These can be timezone, restrictions, currency, user ,device. You can specify multiple data types by using , as a separator. By default all these types will be sent, but it is dependant on your plan what will be returned.

JSON Response Example

    "status": "returned timezone, restrictions, currency, user, device for",
    "error_code": 200,
    "output": {
      "host": "",
      "isp": "Telefonica del Peru",
      "location": {
        "country": {
          "phone_code": "+51",
          "tld": ".pe",
          "iso": "PE",
          "name": "Peru",
          "continent": "SA"
        "latitude": -12.05,
        "longitude": -77.04,
        "city": "",
        "state": ""
      "gdpr": false,
      "restricted": {
        "crypto": false,
        "porn": false,
        "torrents": false
      "timezone": {
        "utc": "America\/Lima",
        "dst": false,
        "offset": -5,
        "name": "SA Pacific Standard Time",
        "local_time": "2019-02-28 21:02:44"
      "user": {
        "name": "Joe Barbour",
        "email": "",
        "phone": "",
        "age": 27,
        "sex": "male"
      "currency": {
        "symbol": "S\/.",
        "code": "S\/.",
        "decimal": 2,
        "name": "Peruvian Nuevo Sol"
      "device": {
        "browser": "Unknown",
        "platform": "Mac"

iOS Intergration

Setup Ovatar can be installed manually by downloading the repo via Github and adding all the & OOvatarIcon header and implementation files.


by adding adding the project though Coccopods (Recommended)

pod 'Ovatar-iOS'


import OOvatar

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
    OOvatar.sharedInstance(withAppKey: "app_key")
    return true

Objective C

#import "OOvatar.h"

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	[OOvatar sharedInstanceWithAppKey:@"app_key"];
    [[OOvatar sharedInstance] setDebugging:true];
    return true;


Ovatar Icon (The Easy Way) To make it quick and easy to get ovatar up and running in your app we designed the OOvatarIcon. This is a powerful class that handles...

  • downloading images from a key or query (email or phone number)
  • image caching
  • automatic image repositioning and sizing
  • face detection
  • image selection and uploading with progress
  • fullscreen previews
  • image size management
  • Adding the OvatarIcon


    add the OOvatarIcon framework

    import OOvatarIcon

    var ovatar: OOvatarIcon?

    	ovatar = OOvatarIcon(frame: CGRect(x: (bounds.size.width / 2) - 100.0, y: (bounds.size.height / 2) - 100.0, width: 200.0, height: 200.0))
        ovatar?.placeholder = UIImage(named: "a_custom_placeholder_image")
        ovatar?.oicondelegate = self
        ovatar?.hasaction = true
        ovatar?.preview = false
        ovatar?.allowsphotoediting = true
        ovatar?.onlyfaces = false
        ovatar?.imageDownload(withQuery: "")

    Objective C


    add the OOvatarIcon framework

    #import "OOvatarIcon/OOvatarIcon.h"

    @property (nonatomic, strong) OOvatarIcon *ovatar;


         self.ovatar = [[OOvatarIcon alloc] initWithFrame:CGRectMake((self.bounds.size.width / 2) - 100.0, (self.bounds.size.height / 2) - 100.0, 200.0, 200.0)];
         self.ovatar.placeholder = [UIImage imageNamed:@"a_custom_placeholder_image"];
         self.ovatar.oicondelegate = self;
         self.ovatar.hasaction = true;
         self.ovatar.preview = false;    
         self.ovatar.allowsphotoediting = true;
         self.ovatar.onlyfaces = false;     
         [self addSubview:self.headerOvatar];
    Let's get that Ovatar!

    Querying by Key, Email Address or Phone Number

    Ovatar allows you to query of course images uploaded using your app_key can be called with ease (the use of a key) but you can also query Ovatar images by Email Address or Phone Number and all can be achived by calling


    ovatar?.imageDownload(withQuery: "")

    Objective C

    [self.ovatar setOvatarImage:@"" phonenumber:@"+4477402847283" fullname:@"Tom Hanks" key:@"[upload_key]" originalImage:@""];

    NOTE In addition to passing a query you can also add a 'name'. This will not query user by name but allow you to store the users name for reference in both the Ovatar Dashboard and for later reference when calling the an image.

    NOTE passing an original image URL to originalImage will first migrate this image to ovatar. If you do don't want to migrate images please pass nil


    ovatar?.imageDownload(withQuery:"", name:"Rick Sanchez")

    Objective C

    [self.ovatar imageDownloadWithQuery:@"" name:@"Rick Sanchez"];

    NOTE If you want to query both a key and a email address as fall back simply add this method multiple times.


    		ovatar?.imageDownload(withQuery: "") //email address query
            ovatar?.imageDownload(withQuery: "+44000000000000")//uk phone number query
            ovatar?.imageDownload(withQuery: "my_uploaded_ovatar_key")//query by key

    Objective C

    		[self.ovatar imageDownloadWithQuery:@""];  //email address query
    		[self.ovatar imageDownloadWithQuery:@"+44000000000000"];  //uk phone number query
    		[self.ovatar imageDownloadWithQuery:@"my_uploaded_ovatar_key"]; //query by key
    By default the class will load the images by key. If no image can be found via key it will fallback to any queryies.

    NOTE Some users have reported this not working, this is because they called this before the OOvatarIcon was initialized. Please make sure you add OOvatarIcon to your project first!

    Setting your own icon

    In some cases you may have an avatar icon from another service you would like to use. To do so you can just call


    ovatar?.imageSet(UIImage(named: "my_local_image.png"), animated: true)

    Objective C

    [self.ovatar imageSet:[UIImage imageNamed:@"my_local_image.png"] animated:TRUE]

    Manual Uploading

    We advise using the power of the OOvatarIcon class for selecting, managing and uploading new images but if you do wish to upload an image manually you can do so by calling.


     let imagedata = .uiImageJPEGRepresentation() as? Data
     let metadata = ["copyright": "joe barbour"]
     ovatar?.imageUpdate(withImage: imagedata, info: nil)	

    Objective C

    NSData *imagedata = UIImageJPEGRepresentation([UIImage imageNamed:@"my_selected_image.jpg"], 0.8);
    NSDictionary *metadata = @{@"copyright":@"joe barbour"};
    [self.ovatar imageUpdateWithImage:imagedata info:nil];
    NOTE Metadata is returned by querying the JSON output, this by directly calling the OOvatar class. See more below.

    The Power of the OOvatarIcon


    A placeholder image can be set be set if there is no image available. This can be done by setting the placeholder as a UIImage. If this is not set the default ovatar placeholder will be set, but this done via a remote image request. We recommend setting your own placeholder to match your UI to avoid any empty states.


    there will be occasions in your app where you will want to allow the user to edit/change their avatar and there will be times where you don't. By default, the user will not be able to interact with an image. But you can change this by setting the hasaction = true;. When set to TRUE, tapping on the OOvatarIcon will either call the ovatarIconWasTappedWithGesture delegate method (see more about delegate callbacks below) or launch the default iOS Gallery Picker right from the subview. By default, the Gallery Picker will be presented, but this can be disabled by setting presentpicker = false;

    Only Faces

    Let's say you're building a dating app? Then you won't want your users to have photos of their dog or their holiday, you want accurate photos of that person. By setting onlyfaces = true; the class will quickly detect if the selected image indeed has a human face within. If it does then the image will be uploaded but if the user selects an image without a face then the ovatarIconUploadFailedWithErrors will be called with an NSError. (see below for more information about delegate callbacks)

    Image Editing

    Images sizes are managed by Ovatar directly but cropping is not (currently). To make this easy you can set allowsphotoediting = true; and when the user selects an image from the default iOS Gallery Picker they will be presented with the default iOS cropping tool. Here the user can resize and reposition the image as they see fit. By default this is disabled.


    OOvatarIcon uses low level animations such as crossfades for when new images are loaded and scale 'bounces' when the icon is tapped. All these animations can be disabled by calling animated = false;

    Additionally, for more control you can change the crossfade duration by setting crossfade = 1.0;. By deafult this is 0.6.

    Full Preview

    Sometimes ovatar images maybe just there as a reference point and maybe to small to see. Enabling preview means when the user taps on an image they will be able to see the Ovatar in full screen. Here a higher resolution will be automatically loaded. This can be enabled on any OOvatarIcon that is not editable (hasaction = true;). By default this is disabled, but can be enabled by preview = true;

    Additionally, you can set a custom caption in the full-screen view. This could be information about the user or just about anything. To add this setting previewcaption = "This is my Ovatar Caption"


    When an Ovatar is downloading or uploading a progress spinner/bar will be presented over the OvatarIcon. By default this is enabled but can be disabled by progressloader = false;

    Delegate Callbacks

    For more precice control the OvatarIcon has 4 delegate callbacks. To enable these you must declare the OOvatarIcon as a delegate by oicondelegate = self;


    func ovatarIconWasTapped(withGesture gesture: UITapGestureRecognizer?) {
        //Called if the 'presentpicker' BOOL is set to FALSE (by default it is set to TRUE). Here you can set custom actions for the when the Ovatar Icon is tapped.

    func ovatarIconWasUpdatedSucsessfully(_ output: [AnyHashable: Any]?) {
        //Called if an image is uploaded successfully.

    func ovatarIconUploadFailed() throws {
        //Called if an image cannot be uploaded, see the documentation for error codes.

    func ovatarIconUploading(withProgress progress: Float) {
        //Called everytime the progress of the upload changes. The progress with displayed as in double value on a 0-100 scale.

    Objective C

    -(void)ovatarIconWasTappedWithGesture:(UITapGestureRecognizer *)gesture {
        //Called if the 'presentpicker' BOOL is set to FALSE (by default it is set to TRUE). Here you can set custom actions for the when the Ovatar Icon is tapped.

    -(void)ovatarIconWasUpdatedSucsessfully:(NSDictionary *)output {
        //Called if an image is uploaded successfully.

    -(void)ovatarIconUploadFailedWithErrors:(NSError *)error {
        //Called if an image cannot be uploaded, see the documentation for error codes.

    -(void)ovatarIconUploadingWithProgress:(float)progress {
        //Called everytime the progress of the upload changes. The progress with displayed as in double value on a 0-100 scale.

    Debugging & Options The following can be set from anywhere in your app but we recommend setting the following variables in the didFinishLaunchingWithOptions method in your


    store the users fullname when uploading an ovatar


    OOvatar.sharedInstance().setName("Steve Jobs")

    Objective C

    [[OOvatar sharedInstance] setName:@"Steve Jobs"];


    to enable console debugging simply set



    Objective C

    [[OOvatar sharedInstance] setDebugging:true];

    Gravatar Support

    by default if an avatar cannot be found Ovatar will attempt to fallback on Gravatar. This can be disabled.



    Objective C

    [[OOvatar sharedInstance] setGravatarFallback:false];


    When an ovatar image is initially downloaded it is saved ti the local cache. This it to prevent unnecessary server calls. The caching cannot be disabled but the expiry can be changed by setting


    OOvatar.sharedInstance().setCacheExpirySeconds(60 * 60 * 4)//in seconds

    Objective C

    [[OOvatar sharedInstance] setCacheExpirySeconds:60*60*4];//in seconds