Merchants > API Reference > Endpoints > Supplier

Supplier

In a marketplace, suppliers (e.g. drivers, couriers or restaurants) may also be involved in fraud. This endpoint can be used to send Ravelin more detailed information on suppliers. You can associate suppliers with orders using the order.suppliers field and use the Ravelin dashboard to investigate supplier activity.

You can send us additional information about suppliers at registration using the Registration endpoint.

Field Status Definitions

Required Required fields must be sent. If the data is not sent Ravelin will return an error.

Important Important fields are crucial for performance where that data is relevant for your business.

Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

POST api.ravelin.com/v2/supplier

Show all

timestamp integer required

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

supplier object required

The supplier registering or updating their account profile.

Show definition

supplierId string required

The unique identifier of the supplier.

type string required

The role of the supplier in order fulfilment.

One of:

driver - A taxi driver, private hire driver, chauffeur or other type of person that drives people in a passenger motor vehicle.
courier - A courier, bike courier or delivery driver.
restaurant - A restaurant or cafe that sells prepared food. May also provide delivery.
shop - A shop which sells goods other than prepared food. May also provide delivery.
seller - An individual who sells goods or services and which is not covered by any of the other supplier types.
contentCreator - A supplier that is creating content, for example, music, podcasts or video. The type of content creator should be set in the category field.
promoter - A supplier that promotes music concerts, festivals, sporting events or other events or experiences, or a supplier that promotes products or services, for example an affiliate partner.
other - Any other type of supplier which is not covered by the other types.

groupId string important

The unique identifier of the supplier's parent organisation.

groupName string important

The name of the supplier's parent organisation.

registrationTime integer important

The time that the supplier registered. If this value is unknown, you can set it to the time the request is sent. Ravelin will retain the earliest value you have sent for this supplier ID.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

email string important

The email address of the supplier.

emailVerifiedTime integer optional

The time at which the supplier verified their email, usually by following a link back to your website from an email you sent to their address.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

name string important

The full name of the supplier.

telephone string important

The telephone number of the supplier. Best in E.164 format with an international dialing code.

telephoneVerifiedTime integer optional

The time at which the supplier verified their telephone number, usually by confirming a code from an SMS you sent to the number.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

telephoneCountry string optional

The country the telephone number directs to. Note that the country is not an adequate replacement for the international dialing code in the Dominican Republic or Puerto Rico where multiple dialing codes are used.

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

homeLocation object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

taxAddress object optional

Store tax address information at the time of payout to compare it to suppliers’ other addresses. Tax info maps to each payout object and is immutable. This could be different in any subsequent payouts.

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

market string optional

The logical region in which this supplier exists.

Pattern: ^[0-9a-z-]*$

marketCountry string optional

The logical country for this supplier. Doesn't change when the supplier is briefly abroad.

marketCity string optional

The logical city in which this supplier exists.

Pattern: ^[0-9a-z-]*$

level string optional

The name of the current level of the supplier.

employmentType string optional

This describes how the supplier is employed by your organisation, e.g. "selfEmployed", or "partTime".

transportType string optional

The type of transport this supplier uses.

category string optional

The highest level category that applies to this supplier.

accountType string optional

The type of supplier account.

One of:

INDIVIDUAL - To be used when the supplier account is an individual account, for example an individual person selling goods or an individual person creating content under their own name.
BUSINESS - To be used when the supplier account is a business account, for example when there is a business or organisation or company associated to the supplier account, a shop selling goods, a restaurant selling food, or a business creating content.

accountPlatform string optional

The platform where the supplier account was created.

identityVerified boolean optional

This field would be used to indicate the status of the supplier's identity verification process, which is usually conducted to ensure compliance with anti-money laundering and other regulations.

tags object optional

The tags to set or unset. Use the tag ID followed by true or false, depending on whether you want to set or unset the tag.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

eventType string optional

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

device object optional

The device that the supplier is using.

Show definition

deviceId string required

The ID of the device used by the customer to trigger this update.

ipAddress string important

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

language string important

The ISO 639 code of your customer's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

userAgent string important

The browser user-agent string, if the device represents a web browser - window.navigator.userAgent.

model string optional

The model/identifier name of the device if the device represents a native app. See here for iOS models: https://www.theiphonewiki.com/wiki/Models and here for Google Play supported models: http://storage.googleapis.com/play_public/supported_devices.csv.

os string optional

The operating system that the device is running.

type string optional

The type of device.

One of: computer, phone, or tablet.

manufacturer string optional

The maker of the device.

location object optional

The geolocated position of the device.

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

browser string optional

deprecated

The name of the web browser being used, if applicable. Prefer userAgent.

javascriptEnabled boolean optional

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean optional

deprecated

Whether cookies are enabled on the web browser.

screenResolution string optional

deprecated

The resolution of the screen on the device in the format XxY

nationalIdentifications array optional

Identifications are used by online suppliers to verify their real-world identity. These forms of identification can be authenticated with government authorities or authorised third-parties to confirm the credentials are legitimate. Extra steps should be taken to confirm the supplier is the legitimate holder of these credentials.

Show definition

driversLicense object optional

A driving license permitting the holder to operate one or more types of motorized vehicle.

Show definition

idNumber string required

The number unique to this piece of identification within the jurisdiction country/state.

For privacy reasons, Ravelin recommends obfuscating the real number by peppering and hashing it, using consistent one-way hashing function such as SHA256.

jurisdictionCountry string required

The controlling country for this form of identification. A ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

The controlling state within the controlling country for this form of identification. Not just the licence holder's home state. Omit where the identification is controlled by a country-level authority.

name string optional

The name of the identification holder.

passport object optional

A passport certifying the identity and nationality of its holder primarily for the purpose of international travel.

Show definition

idNumber string required

The number unique to this piece of identification within the jurisdiction country/state.

For privacy reasons, Ravelin recommends obfuscating the real number by peppering and hashing it, using consistent one-way hashing function such as SHA256.

jurisdictionCountry string required

The controlling country for this form of identification. A ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

name string optional

The name of the identification holder.

nationalId object optional

National identification cards and numbers, such as the US Social Security Number, Brazilian cédula de identidade, or UK's Insurance Number.

Show definition

idNumber string required

The number unique to this piece of identification within the jurisdiction country/state.

For privacy reasons, Ravelin recommends obfuscating the real number by peppering and hashing it, using consistent one-way hashing function such as SHA256.

jurisdictionCountry string required

The controlling country for this form of identification. A ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

name string optional

The name of the identification holder.

vehicles array optional

Vehicles the supplier owns or uses.

Show definition

plate string required

The vehicle registration or licence plate number.

jurisdictionCountry string required

The country in which this vehicle is registered. A ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

The state in which this vehicle is registered. Not just the licence holder's home state.

make string optional

The vehicle brand.

model string optional

The vehicle product range.

year integer optional

The year that the vehicle was produced.

vin string optional

The vehicle identification number as defined in ISO 3779.

POST https://api.ravelin.com/v2/supplier HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "supplier": {
    "supplierId": "abc-123-ZYZ",
    "groupId": "abc-123",
    "groupName": "Burger Chain",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "GBR",
    "homeLocation": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "taxAddress": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "type": "driver",
    "level": "gold",
    "employmentType": "selfEmployed",
    "transportType": "car",
    "category": "private-hire",
    "accountType": "INDIVIDUAL",
    "accountPlatform": "anchor",
    "identityVerified": false,
    "tags": {
      "foo": true,
      "bar": false
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "nationalIdentifications": [
    {
      "driversLicense": {
        "idNumber": "10261985",
        "jurisdictionCountry": "USA",
        "jurisdictionState": "CA",
        "name": "Marty McFly"
      }
    }
  ],
  "vehicles": [
    {
      "plate": "OUTATIME",
      "jurisdictionCountry": "USA",
      "jurisdictionState": "CA",
      "make": "DeLorean Motor Company",
      "model": "DeLorean",
      "year": 1983,
      "vin": "2GTEK13M081122443"
    }
  ]
}

Feedback

Was this page helpful?