Navee API Overview

Navee is a machine learning platform that helps you to prevent fraud and abuse from user-generated content online. Navee empowers businesses to make accurate, real-time decisions that both improve user experience and increase revenue.

For now, Navee is available for 2 usecases:

  • Rental Platforms;
  • Dating Platforms.

As soon as you start sending data, Navee starts making predictions about the overall quality of a post. Navee represents this risk with a score between 0 and 100, where one hundred represents a sure fraud while zero a legitimate post. Navee’s Risk Scores are generated in a few seconds and sent to the Client's webhook.

If the client subscribed to a plan including Navee's moderation platform, Barinomi, the posts and insights are also sent to the platform for human review. In that case—if a moderator intervenes and changes the status of a post—that decision is also sent to the client's webhook.

The next sections will walk you through Navee's integrations and general Services.

Authentication

Authentication is required for any requests towards the API.

To authenticate your request set a x-api-key:{api_key} name/value pair in the headers.

Rate Limits

Rate limit errors are displayed as HTTP 400 responses with status code 54.

The default rate limits are explained below.

If you need higher rate limits, please contact us for assistance.

  • Navee API
    Rate Limit (requests/second)
  • Rental API
    10 requests/second
  • Dating API
    100 requests/second

Rental API Reference

Every request must contain your API KEY in the headers under the key x-api-key.

POST /api/posts

Send new posts to Navee for analysis.

API Endpoint

Navee API processes JSON payloads through HTTP requests at the following endpoint:

https://api.navee.co/api/posts

Required fields in the json payload
  • post_id
    required · String

    your id for the post

  • topic
    required · String

    rental, sell or vacation

  • price
    required · Integer

    - monthly rent with expenses if topic="rental"

    - sell price if topic="sell"

    - daily price if topic="vacation"

    For European platforms prices are considered to be displayed in euros (€) and are going to be analysed as such.

  • property_surface
    required · Integer

    in square meters

  • picture_links
    required · Array of Strings

    list of picture links

  • country_code
    required · String

    FR for France

    BE for Belgium

    CH for Switzerland

    DE for Germany

    IT for Italy

    ES for Spain

  • zip_code
    required · String

    zip code for the good's location

  • city
    required · String

    city for the good's location

  • title
    optional · String

    title of the post

  • description
    optional · String

    description of the good

  • property_type
    optional · String

    villa, apartment, house, studio or parking

  • address
    optional · String

    street name and number

  • furnished
    optional · Boolean

    whether the good is furnished or not

  • rooms_count
    optional · Integer

    number of rooms

  • floor_number
    optional · Integer

    ground is floor 0

  • user_id
    optional · String

    your id for the user/owner of the post

  • nb_posts_user
    optional · Integer

    number of posts already posted by the user

  • username
    optional · String

    first name + last name or username.

  • ip
    optional · String

    example: "127.0.0.1"

  • email
    optional · String

    email of the user

  • phone_number
    optional · String

    phone number of the user

    example: "+33612345678"

  • user_verified
    optional · Boolean

    whether the profile of the user is verified or not

// Example body POST /api/posts
{
  // Required fields.
  "post_id"       : "f911da54be",
  "topic"       : "rental",
  "price"    : 550,
  "property_surface"    : 25,
  "picture_links"    : ["https://domain.com/picture_1.jpg", "https://domain.com/picture_2.jpg", "https://domain.com/picture_3.jpg", "https://domain.com/picture_4.jpg"],
  "country_code"    : "FR",
  "zip_code"    : "75004",
  "city"    : "Paris",

  // Optional fields.
  "title"    : "Appartement en plein centre ville",
  "description"    : "Bonjour, Je mets en location un appartement proche de la place Daumesnil (Paris 12ème), dans un immeuble récent avec ascenseur",
  "property_type"    : "apartment",
  "address"    : "21 rue du Temple",
  "furnished"    : true,
  "rooms_count"    : 2,
  "floor_number"    : 4,
  "user_id"    : "4a69-8e92-1aba4e280b29",
  "nb_posts_user"    : 0,
  "username"    : "Jean Dupont",
  "ip"    : "127.0.0.1",
  "email"    : "navee@navee.co",
  "phone_number"    : "+33648017698",
  "user_verified"    : true
}

PATCH /api/posts

Update a post if its content has been changed.

Send a request similar to the POST / posts request. In the payload add the post_id and the fields you wish to modify.

API Endpoint

Navee API processes JSON payloads through HTTP requests at the following endpoint:

https://api.navee.co/api/posts

PATCH /api/status

Update status of a post (legit, call required or scam).

API Endpoint

Navee API processes JSON payloads through HTTP requests at the following endpoint:

https://api.navee.co/api/status

Required fields in the json payload
  • post_id
    required · String

    your id for the post

  • status
    required · String

    scam, legit or call required

// Example body PATCH /api/status
{
  // Required fields.
  "post_id": "f911da54be",
  "status": "scam"
}

PATCH /api/archive

Archive or restore a post.

API Endpoint

Navee API processes JSON payloads through HTTP requests at the following endpoint:

https://api.navee.co/api/archive

Required fields in the json payload
  • post_id
    required · String

    your id for the post

  • archive
    required · Boolean

    true or false

// Example body PATCH /api/archive
{
    // Required fields.
    "post_id": "f911da54be",
    "archive": true
}

Dating API Reference

API Endpoint

Navee API processes JSON payloads (/body) via an HTTP request at the following endpoint:

https://api.navee.co/api/posts

Every request must contain your API KEY in the headers under the key x-api-key.

POST /api/posts

Send new posts to Navee for analysis.

REQUIRED FIELDS IN THE JSON PAYLOAD
  • post_id
    required · String
  • picture_links
    optional · Array of Strings

  • age
    optional · Integer
  • name
    optional · String
  • description
    optional · String
  • payload
    optional · Anything

    Can contain anything. Will be returned in the webhook response.

// Example body POST /api/posts
{
  // Required fields.
  "post_id"    : "f911da54be",

  // Optional fields.
  "picture_links"    : ["https://domain.com/picture_1.jpg", "https://domain.com/picture_2.jpg", "https://domain.com/picture_3.jpg", "https://domain.com/picture_4.jpg"],
  "age"    : 21,
  "name"    : "Leila",
  "description"    : "Pour rencontrer le prince charmant",
  "payload"    : ...
}

PATCH /api/posts

Update a post/profile if its content has been changed.

Send a request similar to the POST /api/posts request. In the payload add thepost_id and the fields you wish to modify.

PATCH /api/status

Update status of a post (legit, warning or scam) and optionally add it to the fraud base.

API Endpoint

Navee API processes JSON payloads through HTTP requests at the following endpoint:

https://api.navee.co/api/status

Required fields in the json payload
  • post_id
    required · String

    your id for the post

  • status
    required · String

    scam, legit or warning

  • fraud_base
    optional · Hash

    Optionnal field. If the field is present, the fraud is gonna be added to the fraud base.

    • ban_reason
      optional · String

      Reason of the ban. Choose between one of this 4 categories:


      fake_profile if there is a mismatch between the profile and the person behind it.

      prostitution if proposal of sexual activity with payment

      bad_behaviour if the profile is real but the person has misbehaved

      other if reason not in one of the above categories


      Content of this field is gonna be shared with other platforms.

    • ban_message
      optional · String

      Addionnal information on the ban reason


      Content of this field is gonna be shared with other platforms.

    • payload
      optional · Anything

      Any information you want to associate to the ban profile.


      Content of this field is gonna be return only to your platform. It is private and it is not gonna be shared accross platform

// Example body PATCH /api/status
{
  // Required fields.
  "post_id"       : "f911da54be",
  "status"    : "scam",

  // Optional fields.
  "fraud_base"    : {"ban_reason": "prostitution", "ban_message": "my message", "payload": "my payload"}
}

Rise API Reference

API Endpoint

Navee API processes JSON payloads (/body) via an HTTP request at the following endpoint:

https://api.navee.co/api/posts

Every request must contain your API KEY in the headers under the key x-api-key.

POST /api/posts

Send new pictures to Navee for analysis.

REQUIRED FIELDS IN THE JSON PAYLOAD
  • post_id
    required · String
  • picture_links
    optional · Array of Strings 

// Example body POST /api/posts
{
  // Required fields.
  "post_id"    : "f911da54be",
  "picture_links"    : ["https://domain.com/picture_1.jpg"],
}

API Responses

A successful API request will respond with an HTTP 200. An invalid API request will respond with an HTTP 400. The response body will be a JSON object describing why the request failed. If Navee’s servers are dealing with unexpected problems, you’ll get an HTTP 500 response. An above-zero status indicates an error.

Possible Status Codes

  • -1
    Success but warning message
  • 0
    Success
  • 50
    Invalid Request
  • 51
    Invalid API Key
  • 52
    Missing required field
  • 53
    Invalid field
  • 54
    Conflicting fields selected
  • 55
    Invalid JSON in request
  • 60
    Post (/user) id not unique (for POST REQUEST)
  • 61
    Unknown post (/user) id (for PATCH REQUEST)
  • 70
    Rate limited
  • 71
    Maximum number of requests made
  • 100
    Unexpected server-side error

Response body contains a JSON with the status_code and a message field.

{
      "status_code": 52,
      "message": "post_id field is missing"
}

Decision Webhooks

Decision Webhooks are sent to the pre-defined URL after Navee's initial analysis or your moderator's review.

Rental Webhook

Decision Webhooks for rental contain a risk_score field between 0 and 100, a method field equals to "automatic" or "manual" depending on the source of the decision, the post_id field and results of filters on pictures.

Response

{
  "post_id": "f911da54be",
  "status": "scam",
  "post_risk_score": 73,
  "user_risk_score": 93,
  "method": "automatic",
  "explanation": "Email black-listed",
  "is_duplicate": true,
  "duplicate_post_ids": ["8ce2e75c", "93a3b1c0", "9648cab4", "9a712294"]
}

Response Fields

  • post_id
    String

  • status
    String

    Final decision about the post status.

    legit, call required or scam

  • post_risk_score
    Integer

    Post score between 0 and 100, where risky posts have higher scores.

  • user_risk_score
    Integer

    User score between 0 and 100, where risky posts have higher scores.

  • method
    String

    equals to automatic if the result comes from our Machine Learning algorithms.

    equals to manual if the result comes from manual moderator.

  • explanation
    String

    Quick text describing the reason of the moderation.

  • is_duplicate
    String

    Whether the post is duplicated with another post of the history or not.

  • duplicate_post_ids
    Array of Strings

    List of post_ids corresponding to posts that are duplicated (similar pictures and information) with current post.

    Always empty when is_duplicate is false.

Dating Webhook

Decision Webhooks for dating contain a method field equals to "automatic" or "manual" depending on the source of the decision , a post_id field, a risk_score field between 0 and 100, a status field which determines whether it is a fraud or not based on the risk score, a duplicate_pictures field listing all duplicated pictures found online, a filters_pictures field listing results of filters on all pictures and a fraud_base field listing information about duplicated profiles found in the fraud base.

Response

{
  "post_id": "f911da54be",
  "method": "automatic",
  "risk_score": 73,
  "status": "fraud",
  "duplicate_pictures": {"https://domain.com/picture_1.jpg": [], "https://domain.com/picture_2.jpg": ["link_1_found_online", "link_2_found_online"]},
  "filters_pictures": {"https://domain.com/picture_1.jpg": {"adult_content": true, "violent_content":true, "provocative_content": true, "adult_content_score": 99, "violent_content_score":52, "provocative_content_score": 71, "quality_score": 100, "face_detected": true}, "https://domain.com/picture_2.jpg": {"adult_content": false, "violent_content": false, "provocative_content": false, "adult_content_score": 0, "violent_content_score": 10, "provocative_content_score": 25, "quality_score": 33, "face_detected": false}},
  "fraud_base": [{"ban_reason": "fake_profile", "ban_message": null, "ban_date": "2019-08-29", "payload": null, "duplicate_pictures": ["https://domain.com/picture_1.jpg", "https://domain.com/picture_2.jpg"]}, {"ban_reason": "bad_behaviour", "ban_message": "my ban message", "ban_date": "2018-12-22", "payload": "mypayload", "duplicate_pictures": ["https://domain.com/picture_2.jpg"]}],
  "age_range": {"low": 23, "high": 34},
  "gender": "male",
  "payload": ...
}

Response Fields

  • post_id
    String

  • method
    String

    equals to automatic if the result comes from our Machine Learning algorithms.

    equals to manual if the result comes from manual moderator.

  • risk_score
    Integer

    Score between 0 and 100, where risky posts have higher scores.

  • status
    String

    fraud, warning or legit

  • duplicate_pictures
    Hash

    Keys are urls of the original pictures and value is the list of duplicate pictures found online.

  • filters_pictures
    Hash

    Keys are urls of the original pictures and value is a hash containing results of each filter on pictures.

    • adult_content
      Boolean

      Whether adult content has been detected or not in the picture.

    • adult_content_score
      Integer

      Score between 0 and 100. Higher is the score, higher is the probability of adult content in the picture.

    • violent_content
      Boolean

      Whether violent content has been detected or not in the picture.

    • violent_content_score
      Integer

      Score between 0 and 100. Higher is the score, higher is the probability of violent content in the picture.

    • provocative_content
      Boolean

      Whether provocative content has been detected or not in the picture.

    • provocative_content_score
      Integer

      Score between 0 and 100. Higher is the score, higher is the probability of provocative content in the picture.

    • quality_score
      Integer

      Score between 0 and 100. Equals to 100 if a face is clearly visible in the picture. Equals to 0 if no face is visible in the picture.

    • face_detected
      Boolean

      Whether at least one face has been detected or not in the picture.

  • fraud_base
    List of Hashes

    List of banned profiles found on the fraud base which contain at least one duplicated picture.

    A list of hashes is returned. One hash correspond to one banned profile.

    • ban_reason
      String

      Can be one of the following 4 category:

      fake_profile if there is a mismatch between the profile and the person behind it.

      prostitution if proposal of sexual activity with payment.

      bad_behaviour if the profile is real but the person has misbehaved.

      other if reason not in one of the above categories.

      Can be null if unknown reason.

    • ban_message
      String

      Message associated to the ban reason.

      Can be null if no message is associated to the ban.

    • ban_date
      String

      Date of the ban under the format "yyyy-MM-dd".

      Can be null if unknown date.

    • payload
      Anything

      Return the exact payload sent initially. Only if the profile come from your platform.

      Can be null if the ban come from another platform or if no payload has been provided.during the initial request.

    • duplicate_pictures
      List of String

      List of pictures common to both profiles.

  • age_range
    Hash

    Age range for the main person on the profile.

    Can be null if no face or too many faces are detected in the picture.

    • low
      Integer

      Lower bound of the age

    • high
      Integer

      Higher bound of the age

  • gender
    String

    "female" or "male".

    Can be null if no face or too many faces are detected in the picture.

  • payload
    Return the exact payload sent in the initial request.

Rise Webhook

Decision Webhooks for Rise contain a post_id field and a duplicate_pictures field listing all duplicated pictures found online.

Response

{
  "post_id": "f911da54be",
  "duplicate_pictures": {"https://domain.com/picture_1.jpg": [], "https://domain.com/picture_2.jpg": ["link_1_found_online", "link_2_found_online"]},
}

Response Fields

  • post_id
    String

  • duplicate_pictures
    Hash

    Keys are urls of the original pictures and value is the list of duplicate pictures found online