Basics

The HEROLD CNAM-Service (Caller-ID Name) is a HTTP-based service for retrieving a callers name for a provided phone number or searching for a specific company or person by name and address.

In order to use the service you must always provide valid credentials, as authentication is required for each request - for more information, see the Authentication chapter .

The provided phone numbers should be in E.164 format beginning with +43 as only Austrian phone numbers are supported. The HEROLD CNAM-Service will, nevertheless, try to parse a phone number not provided in E.164 format and probably also return a valid result, however, to improve the success rate, the E.164 format should be used whenever possible.

The service can return the requested data in various formats and may be configured to return only one or multiple results, even containing only specific fields. The default configuration, however, will return one matching result in JSON format with a default set of fields.

Playground

With your API-Key you can use the Playground to learn about all the possibilities this service provides.

Using the Service

To use the service simply provide the phone number with any of the arguments explained in detail below.

Here's a simple example service call, searching for a phone number:

Authentication

Every request to the HEROLD CNAM-Service requires authentication, either by providing an authentication key or via HTTP basic authentication.

1. Providing an Authentication Key

The authentication key can be added to each request as a request parameter called authkey . This is the easiest way to authenticate against the service, but if you have any kind of request logging enabled in your application, the authentication key will probably appear in your logs.
If you wish to authenticate via HTTP basic authentication, continue to the next chapter.

2. Using HTTP Basic Authentication

HTTP Basic authentication enables you to send the required credentials via HTTP header parameters. In this case you must provide a username and password, where the username is your account-id and the password is your authentication key. Please see this link for further information about HTTP basic authentication.

Response Formats

The HEROLD CNAM-Service can return the requested data in various formats. You may specify the format as a request parameter called format or via the HTTP accept header .

Currently, the following formats are supported:

Format	Request parameter	Accept header
JSON (default)	format=json	application/json
JSONP	format=jsonp	application/javascript
TEXT	format=text	text/plain
XML	format=xml	application/xml

JSON

JSON is the default response format or is being used if the request parameter format=json or the HTTP accept header application/json are set. The matching results are always returned as a collection, even if only one match has been found. See "Using the Service" for an example.

JSONP

Using JSONP, the JSON response is wrapped in a JavaScript callback using the request parameter format=jsonp or the HTTP accept header application/javascript. You can also specify the name of the callback function by passing a callback argument. The default callback function name is callback.

Example

TEXT

The text format simply returns a ";"-separated list of fields using the request parameter format=text or the HTTP accept header text/plain Multiple records are separated by the "|" character. Multiple field values are enclosed in square brackets and separated by the ";" character.

Example

XML

The xml format is used by specifying the request parameter format=xml or the HTTP accept header application/xml.

Example

Limiting the Results

In some cases, the service may return more than one result. This is the case for example, if the phone number is shared by multiple companies or if there is a record in the yellow- as well as the white-pages. If you need to retrieve all or a custom number of results, you may specify the request parameter called return . This parameter can be set to a number between 1 and 100 or to the string all .

If a request returns more than one result from both yellow- and white-pages, the results of the yellow-pages are always returned before the results of the white-pages.

Example

In this example, 4 records are returned: 3 from the yellow- and 1 from the white-pages.

Understanding Fields and Customizing the Results

The HEROLD CNAM-Service can be configured to return only the required response fields or a pre-defined group of fields. Currently the following fields are supported:

Name	Description
source	The source of the record. This value can be yp for yellow-pages and wp for white-pages.
name	The name of the record. This is either a company name or the last-/surname in cases of a person record.
firstname	The first-/given-name. Only available for person records.
title	The title. Only available for person records.
street	The street name of the postal address.
housenumber	The house number of the postal address.
postalcode	The postal code.
city	The city.
phone	The phone number in E.164 format. This value can be returned as a list, in cases a record has multiple phone numbers.
fax	The fax number in E.164 format. This value can be returned as a list, in cases a record has multiple fax numbers. Only available for company records.
email	The email address. This value can be returned as a list, in cases a record has multiple email addresses. Only available for company records.
web	The web address. This value can be returned as a list, in cases a record has multiple web addresses. Only available for company records.
id	The id of the record. This value may be used to match the records with your database or use it with another service

In addition, there are 3 pre-defined sets of fields available:

Name	Description	Available fields
default	The default set of fields	source, name, firstname, title, street, housenumber, postalcode, city, phone
simple	A simple, basic set of fields	source, name, firstname, title
all	A set of all available fields	source, name, firstname, title, street, housenumber, postalcode, city, phone, fax, email, web, id

In order to return the required fields, you can specify the fields request parameter. This can be either set to a group of fields, e.g. fields=all or to a list of specifid fields by setting the request parameter multiple times, e.g. ...&fields=name&fields=firstname&fields=city .

Example

Passthrough Data

Passthrough data allows you to pass custom parameters to the service which are then returned for the specified name(s). This can be useful if special control values are required in order to process the response. Passthrough data may be added via the passthrough request parameter. You may specify multiple passthrough parameters by adding the request parameter multiple times.

Example

Searching for companies or persons by name and address

The HEROLD CNAM-Service also supports querying the underlying data by name and address. The URL to access this service is /v1/query.
The following fields are available as search parameters:

Name/URL parameter	Description
name	The name. This is either a company name or the last-/surname in cases of a person search.
firstname	The first-/given-name. Only available for person records.
street	The street name of the postal address.
housenumber	The house number of the postal address.
postalcode	The postal code.
city	The city.

In order to query the results, you must provide valid search criteria via url parameters.

Example

You may use all other response- and format-settings as described above.
The maximum number of results returned by the service is 10!

Account status

You can check the status of your account. You must provide your credentials the same way you do for the regular service. For more information, see the Authentication chapter
. The first two entries of the result show the total number of requests you made in the current month and your limit for the current month. The history shows the numbers of requests in the last twelve months. It also shows how many of these requests returned a result, did not return a result or returned an error.

API status

You can check the status of the api. If the api is up and running you will see the text CNAM Service is running. No credentials are needed for this request.

Service Status-Codes and Errors

The HEROLD CNAM-Service sends default HTTP status codes with each response. These status codes should be handled accordingly as everything other than 200 means that no record could be found or indicates an error in the processing of the request.

The following status codes may be returned:

Status-Code	Name	Description
200	OK	The request could be handled successfully and at least one record could be returned.
400	BAD REQUEST	This usually indicates an invalid request parameter or an invalid phone number. In cases of an invalid phone number, a corresponding message is returned.
401	UNAUTHORIZED	The provided authentication key or HTTP basic authentication parameters are not valid.
404	NOT FOUND	No match could be found for the specified phone number.
500	INTERNAL SERVER ERROR	An internal server error occurred. This indicates an unhandled problem with the request or may occur due to server-downtime or maintenance.