Contact Resource

Introduction

The Contact resource provides information about individuals or entities associated with a product, such as their role, contact details, and location.

Contact Object

The Contact resource includes the following fields:

Field	Type	Description	Possible values	Default
_id	Integer	Unique identifier for the contact	-	-
_links	Object	Hyperlinks to related resources	-	-
product_type	String	Type of product associated with the contact	book, ebook, audiobook	-
product_contact_role	String	Role of the contact in relation to the product	Role ID values (ONIX codelist 198)	-
country	String	Country code of the contact	ISO 3166-1 alpha-2 codes	Null
email_address	String	Email address of the contact	Valid email format	Null
location_name	String	Name of the location	-	Null
postal_code	String	Postal code of the location	-	Null
product_contact_name	String	Name of the contact person	-	Null
street_address	String	Street address of the contact	-	Null
telephone_number	String	Telephone number of the contact	Valid phone number format	Null

Managing Contact Resources

GET: Retrieving a Contact

A contact of the product with the id PRODUCT_ID can be fetched by its unique ID using an HTTP GET request.

Endpoint

GET https://api.openpublishing.com/resource/v3/products/[PRODUCT_ID]/contacts/[ID]

Response Structure

The response is a JSON object with the contact object.

POST: Creating a New Contact

New contact resources can be added to the product resource using an HTTP POST request. The request must include all required fields for the resource in the body.

Endpoint

POST https://api.openpublishing.com/resource/v3/products/[PRODUCT_ID]/contacts

Request Body Example

{
    "country": "US",
    "email_address": "dwight.schrute@dundermifflin.com",
    "location_name": "Scranton / Pennsylvania",
    "postal_code": "18501",
    "product_contact_name": "Dwight Schrute",
    "product_contact_role": "10",
    "product_type": "book",
    "street_address": "1725 Slough Avenue",
    "telephone_number": "+1 999 424 55"
}

PUT: Updating an Existing Contact

Existing contact resources can be updated using an HTTP PUT request. The request body should contain the updated fields.

Endpoint

PUT https://api.openpublishing.com/resource/v3/products/[PRODUCT_ID]/contacts/[ID]

Request Body Example

{
    "product_contact_name": "Dwight Schrute",
    "telephone_number": "+1 999 123 456"
}

DELETE: Deleting a Contact

Contact resources can be deleted using an HTTP DELETE request. This action permanently removes the resource.

Endpoint

DELETE https://api.openpublishing.com/resource/v3/products/[PRODUCT_ID]/contacts/[ID]

Resource Queries

Querying Contacts (GET)

Endpoint

GET https://api.openpublishing.com/resource/v3/products/[PRODUCT_ID]/contacts

This endpoint supports filters and pagination for querying contact data. Please refer to resource queries syntax to filter and refine your search results.

Response Structure

Field	Type	Description
_links	Object	Links to related resources
items	Array	An array of individual contact objects

Each item in the items array represents a single contact.

Query Parameters

Parameter	Description	Notes
product_contact_role	Filter by contact role ID	Supports equal-operator (exact match) only
product_type	Filter by product type	Supports equal-operator (exact match) only
product_contact_name	Filter by contact name	Supports resource queries syntax

Examples

Example 1: Querying Contacts by Role (Product safety contact)

GET https://api.openpublishing.com/resource/v3/products/3188/contacts?product_contact_role=10

Example 2: Filter Contacts by Name

GET https://api.openpublishing.com/resource/v3/products/3188/contacts?product_contact_name__contains=dwight