Brokers

This endpoint is aimed at brokers that want to automate a territory check against a territory network.

You will need to work with our development team to be granted access to this API.

Brands who wish to allow you access to search their network should contact us to provide a value for “brandId”. This will create a link between them and you and will allow you to search against them when provided within the request body.

URL

https://api.vision-mapping.com/territory-checker/v2/brokers/search?apiKey=

Method

POST

Request body

{

“brandIds”: [

                                “string”

],

“searchPhrase”: “string”

“region”: “string”

}

brandIds: A string collection which must contain at least one item. There is currently no limit to the number of brandIds that can be provided in a single request. Each brandId must be between 1 and 100 characters.

searchPhrase: The location to start the search from. It can either be a ZIP code, or a partial/full address which must still contain a ZIP code. Must be between 1 and 250 characters.

region: Allows us to treat searchPhrase appropriately. Currently, the only valid value is “US”.

Successful response

200 OK

{

                “brands”: [

                                “brandId”: “string”,

                                “availability”: “string”,

                                “searchRadiusInMetres”: double

                ]

}

brandId: The same brandId sent in the request to match on.

availability: Either “Available”, “Unavailable” or “Pending”.

searchRadiusInMetres: The distance radius searched (in metres) for availability. This value is customised by the brand.

Note: It is possible to receive fewer results than requested, e.g. you provided 5 brandIds but the response collection only contains 3 items. This could be for a variety of reasons such as:

• The individual brandId is invalid or the brand has revoked your access to search against them
• The brand is no longer subscribed to Vision
• An error occurred while processing that particular brand

Other possible responses

400 BadRequest

One or more parameters were missing or failed validation.

The response will be in the problem+json format with details on the parameter(s) that failed validation. See below for an example:

{

   "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",

   "title": "One or more validation errors occurred.",

   "status": 400,

   "errors": {

       "BrandIds": [

           "One or more brands must be provided to search against."

       ]

   },

   "traceId": "00-2689d71448480f67b91c7ab47ecacd01-ec2cfb0da02164e4-00"

}

401 Unauthorised

The apiKey provided is either invalid, or you have not been registered as a broker. Contact us to resolve this.

422 Unprocessable Entity

We were unable to determine a location from searchPhrase, and cannot proceed any further.

429 Too Many Requests

This API is rate limited to no more than 10 requests per second.

500 Internal Server Error

Something went wrong at our end.