Send information about an end-user (generic end-point)

Use this endpoint to feed the Nexway DMP with newly acquired information about an end-user (that may or may not already be known to Nexway). The event might simply contain information pertaining to an end-user or it can relate to an action done by a end-user. All fields of the User structure which are not explicitely mandatory can safely be left missing.

Request

POST https://api.nexway.store/event

Request body

The request body takes a complete Event resource, containing the following writable properties:

{
    "_meta": {
        "customerID": "string",
        "dataAcquisitionTime": "int64",
        "nexwaySalesunitID": "string",
        "originStore": "string",
        "platformID": "string",
        "siteLanguage": "string"
    },
    "action": "string",
    "actionTime": "int64",
    "cart": {
        "URL": "string",
        "currency": "string",
        "id": "string",
        "items": [
            {
                "pricing": {
                    "VATRate": "float",
                    "discountConstant": "float",
                    "discountRate": "float",
                    "unitPriceExcludingVAT": "float",
                    "unitPriceIncludingVAT": "float"
                },
                "product": {
                    "name": "string",
                    "nexwayID": "string",
                    "packshots": [
                        {
                            "URL": "string",
                            "height": "integer",
                            "width": "integer"
                        }
                    ],
                    "uniqueReference": "string"
                },
                "quantity": "integer"
            }
        ]
    },
    "order": {
        "CCExpirationDate": "date",
        "cartId": "string",
        "cartUrl": "string",
        "currency": "string",
        "id": "string",
        "items": [
            {
                "licenceNumbers": [
                    "string"
                ],
                "pricing": {
                    "VATRate": "float",
                    "discountConstant": "float",
                    "discountRate": "float",
                    "unitPriceExcludingVAT": "float",
                    "unitPriceIncludingVAT": "float"
                },
                "product": {
                    "name": "string",
                    "nexwayID": "string",
                    "packshots": [
                        {
                            "URL": "string",
                            "height": "integer",
                            "width": "integer"
                        }
                    ],
                    "uniqueReference": "string"
                },
                "quantity": "integer"
            }
        ],
        "paymentMethod": "string",
        "paymentStatus": "string"
    },
    "registrations": [
        {
            "licenceNumber": "string",
            "product": {
                "name": "string",
                "nexwayID": "string",
                "packshots": [
                    {
                        "URL": "string",
                        "height": "integer",
                        "width": "integer"
                    }
                ],
                "uniqueReference": "string"
            }
        }
    ],
    "usage": {
        "product": {
            "name": "string",
            "nexwayID": "string",
            "packshots": [
                {
                    "URL": "string",
                    "height": "integer",
                    "width": "integer"
                }
            ],
            "uniqueReference": "string"
        },
        "type": {}
    },
    "user": {
        "FTIN": "string",
        "VATIN": "string",
        "addresses": [
            {
                "city": "string",
                "country": "string",
                "state": "string",
                "street": "string",
                "zipcode": "string"
            }
        ],
        "birthDate": "date",
        "companyName": "string",
        "companyRegistrationNumber": "string",
        "companySizeFreeRange": {
            "lowerBoundInclusive": "integer",
            "upperBoundInclusive": "integer"
        },
        "companySizeRange": "string",
        "country": "string",
        "email": "/\\A([\\w+\\-](\\.[\\w+\\-])?)+@[a-z\\d\\-]+(\\.[a-z]+)*\\.[a-z]+\\z/i",
        "firstName": "string",
        "gender": "string",
        "language": "string",
        "lastName": "string",
        "marketingConsents": [
            {
                "status": "string",
                "topic": "string"
            }
        ],
        "middleName": "string",
        "networkIdentities": [
            {
                "identifier": "string",
                "platform": "string"
            }
        ],
        "phoneNumbers": [
            "string"
        ],
        "preferredCurrency": "string",
        "title": "string",
        "username": "string"
    }
}

Properties

Name Type Description Additional
_meta object

information about the data you transmit

Optional
_meta.customerID string

An id identifying the customer in Nexway System. Make sure you know the proper ID(s) before sending your message , if you don't contact your POC at Nexway to get the IDs.

Optional
_meta.dataAcquisitionTime int64

when the data has been acquired, elapsed seconds since Jan, 1st 1970 UTC. If unknown do no provide this field or set it to 0.

Optional
_meta.nexwaySalesunitID string

An id identifying the point of sales (or service) in Nexway System. Make sure you know the proper ID(s) before sending your message , if you don't contact your POC at Nexway to get the IDs.

Optional
_meta.originStore string

A string identifying the source of the message. The format is free (as far as this API is concerned), and should be created following a convention between the client and Nexway (Contact agency_dm@nexway.com in doubts).

Optional
_meta.platformID string

An id identifying the platform in Nexway System. Make sure you know the proper ID(s) before sending your message , if you don't contact your POC at Nexway to get the IDs.

Optional
_meta.siteLanguage string Optional
action string

Possible values are:

  • send data
  • order
  • register licences
  • cancel order
  • use product
  • cart
actionTime int64

when did the action happended, in elapsed seconds since epoch UTC

Optional
cart object Cart Optional
cart.URL string

The unique link to retrieve this cart

Optional
cart.currency string
cart.id string

The unique identifier of the cart, in your referential, for further reference

Optional
cart.items[] array
cart.items[].pricing object Pricing
cart.items[].pricing.VATRate float

the VAT rate, if given, must be the tax ratio, for instance 0.2 is VAT is 20%

cart.items[].pricing.discountConstant float

the discount constant value

cart.items[].pricing.discountRate float

the discount rate, for instance 0.1 is discount rate is 10%

cart.items[].pricing.unitPriceExcludingVAT float
cart.items[].pricing.unitPriceIncludingVAT float
cart.items[].product object

A product you or your managed publisher sells through Nexway.

cart.items[].product.name string

human-readable name of the product, it is not required to be immutable regarding the product id, especially considering translations.

cart.items[].product.nexwayID string

the unique ID of this product, in Nexway catalog. Optional.

Optional
cart.items[].product.packshots[] array

packshots of the product, optional unless the event action =='cart'

Optional
cart.items[].product.packshots[].URL string

where the image can be found

cart.items[].product.packshots[].height integer

the height of the image in pixels

cart.items[].product.packshots[].width integer

the width of the image in pixels

cart.items[].product.uniqueReference string

A unique identifier for the product. This id must be uniquely attached to a product in your information system, and be eternally immutable.

cart.items[].quantity integer

The number of product hat was in cart

order object Order Optional
order.CCExpirationDate date

The day the credit card will expire. RFC3339 date-only format (yyyy-mm-dd). If day is unknown set 01 as dd

Optional
order.cartId string

The unique identifier of the related cart

Optional
order.cartUrl string

The unique link to retrieve the related cart

Optional
order.currency string
order.id string

The unique identifier of the order, in your referential, for further reference

order.items[] array
order.items[].licenceNumbers[] array of string Optional
order.items[].pricing object Pricing
order.items[].pricing.VATRate float

the VAT rate, if given, must be the tax ratio, for instance 0.2 is VAT is 20%

order.items[].pricing.discountConstant float

the discount constant value

order.items[].pricing.discountRate float

the discount rate, for instance 0.1 is discount rate is 10%

order.items[].pricing.unitPriceExcludingVAT float
order.items[].pricing.unitPriceIncludingVAT float
order.items[].product object

A product you or your managed publisher sells through Nexway.

order.items[].product.name string

human-readable name of the product, it is not required to be immutable regarding the product id, especially considering translations.

order.items[].product.nexwayID string

the unique ID of this product, in Nexway catalog. Optional.

Optional
order.items[].product.packshots[] array

packshots of the product, optional unless the event action =='cart'

Optional
order.items[].product.packshots[].URL string

where the image can be found

order.items[].product.packshots[].height integer

the height of the image in pixels

order.items[].product.packshots[].width integer

the width of the image in pixels

order.items[].product.uniqueReference string

A unique identifier for the product. This id must be uniquely attached to a product in your information system, and be eternally immutable.

order.items[].quantity integer

The number of products that was ordered

order.paymentMethod string

The payment method using which the end-user paid the order

Possible values are:

  • amex
  • bank_transfer
  • boleto
  • cartebleue
  • cb
  • cheque
  • clickandbuy
  • diners
  • discover
  • elo
  • elv
  • eps
  • express_checkout
  • giropay
  • hipercard
  • ideal
  • ing_homepay
  • invoice
  • jcb
  • maestro
  • mastercard
  • mistercash
  • paylib
  • paypal
  • postepay
  • sofort
  • sofortbanking
  • visa
  • visa_electron
  • wha
  • slimpay
  • sepa
  • pse
  • baloto
  • efecty
  • bnl
  • checkout
  • bank_transfer_nl
  • nordea
  • digital_goods
  • pass
  • paysafecard
  • wafacash
Optional
order.paymentStatus string

Possible values are:

  • accepted
  • refused
  • fraud
  • pending
  • cancelled
Optional
registrations[] array Optional
registrations[].licenceNumber string

product licence number

Optional
registrations[].product object

A product you or your managed publisher sells through Nexway.

Optional
registrations[].product.name string

human-readable name of the product, it is not required to be immutable regarding the product id, especially considering translations.

registrations[].product.nexwayID string

the unique ID of this product, in Nexway catalog. Optional.

Optional
registrations[].product.packshots[] array

packshots of the product, optional unless the event action =='cart'

Optional
registrations[].product.packshots[].URL string

where the image can be found

registrations[].product.packshots[].height integer

the height of the image in pixels

registrations[].product.packshots[].width integer

the width of the image in pixels

registrations[].product.uniqueReference string

A unique identifier for the product. This id must be uniquely attached to a product in your information system, and be eternally immutable.

usage object Usage Optional
usage.product object

A product you or your managed publisher sells through Nexway.

Optional
usage.product.name string

human-readable name of the product, it is not required to be immutable regarding the product id, especially considering translations.

usage.product.nexwayID string

the unique ID of this product, in Nexway catalog. Optional.

Optional
usage.product.packshots[] array

packshots of the product, optional unless the event action =='cart'

Optional
usage.product.packshots[].URL string

where the image can be found

usage.product.packshots[].height integer

the height of the image in pixels

usage.product.packshots[].width integer

the width of the image in pixels

usage.product.uniqueReference string

A unique identifier for the product. This id must be uniquely attached to a product in your information system, and be eternally immutable.

usage.type object

The type of usage the end-user is make of the product

Possible values are:

  • start_trial
  • end_trial
  • start_freemium
  • end_freemium
Optional
user object User
user.FTIN string

Federal Tax Identification Number

Optional
user.VATIN string

Valuer-Added Tax identification number

Optional
user.addresses[] array Optional
user.addresses[].city string Optional
user.addresses[].country string
user.addresses[].state string Optional
user.addresses[].street string

street number and street name, may contain unix EOL characters (ascii 0x0A).

Optional
user.addresses[].zipcode string
user.birthDate date

RFC3339 date-only format (yyy-mm-dd)

Optional
user.companyName string Optional
user.companyRegistrationNumber string Optional
user.companySizeFreeRange object

This property should be used instead of user.companySizeRange when pre-defined range does not fit your needs.

At least one of lowerBoundInclusive and upperBoundInclusive must be specified.

If both are set then lowerBoundInclusive must be less or equal to upperBoundInclusive.

companySizeFreeRange and companySizeRange cannot be both set in the same message.

Optional
user.companySizeFreeRange.lowerBoundInclusive integer Optional
user.companySizeFreeRange.upperBoundInclusive integer Optional
user.companySizeRange string

size of the end-user company, amongst possible values.

Possible values are:

  • less than or equal to 50
  • 51-200
  • 200-1000
  • more than 1000
Optional
user.country string Optional
user.email /\A([\w+\-](\.[\w+\-])?)+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i Email
user.firstName string Optional
user.gender string

Male(M) of Female(F)

Possible values are:

  • M
  • F
Optional
user.language string Optional
user.lastName string Optional
user.marketingConsents[] array Optional
user.marketingConsents[].status string

Possible values are:

  • accepted
  • refused
  • untold
user.marketingConsents[].topic string

a free-format string identifying the scope of the end-user agreement.

user.middleName string Optional
user.networkIdentities[] array Optional
user.networkIdentities[].identifier string

ID of the end-user on the platform

user.networkIdentities[].platform string

the service this identity is bound to

Possible values are:

  • facebook
  • twitter
  • linkedin
user.phoneNumbers[] array of string Optional
user.preferredCurrency string Optional
user.title string

title as entered by the end-user in its language

Optional
user.username string

username / pseudo / alias ...

Optional

Authorisation

This request requires the use of one of following authorisation methods: BASIC .

Response

The following HTTP status codes may be returned, optionally with a response resource.

Status code Description Resource
204 No Content

request correctly processed, thank you

400 Bad Request

The provided data do not meet requirements

401 Unauthorized

Please authenticate

429

The body of request body has already been processed before

500 Internal Server Error

Internal error

501 Not Implemented

The requested action, although specified, is not yet implemented

503 Service Unavailable

Service is unavailable, please retry later

Example

{
    "_meta": {
        "dataAcquisitionTime": 1.477053592e+09,
        "nexwaySalesunitID": "123",
        "originStore": "My store",
        "siteLanguage": "en"
    },
    "action": "send data",
    "user": {
        "FTIN": "3278124",
        "VATIN": "81234783453",
        "addresses": [
            {
                "country": "GB",
                "street": "1 small street",
                "zipcode": "SW1A 2AA"
            }
        ],
        "birthDate": "1968-05-10",
        "companyName": "doe Inc.",
        "companyRegistrationNumber": "ABC123456",
        "companySizeRange": "more than 1000",
        "country": "gb",
        "email": "john.doe@internet.com",
        "firstName": "john",
        "gender": "M",
        "language": "en",
        "lastName": "doe",
        "marketingConsents": [
            {
                "status": "accepted",
                "topic": "A marketing topic"
            },
            {
                "status": "refused",
                "topic": "Another marketing topic"
            }
        ],
        "middleName": "mc",
        "networkIdentities": [
            {
                "identifier": "jdoe",
                "platform": "facebook"
            },
            {
                "identifier": "jdoe.pm",
                "platform": "linkedin"
            }
        ],
        "phoneNumbers": [
            "25884848684",
            "54561321245"
        ],
        "preferredCurrency": "GBP",
        "title": "Mgr",
        "username": "johndoe"
    }
}

Explore this API

event

an event about an end-user

Request Content-Type
Response Content-Type

Choose an authorisation method:

Username Authentication username to be used for request
Password Authentication password to be used for request
Try it out!