Contact API (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 28, 2017
Version 13Show Document
  • View in full screen mode

The Contact API is used to create, update and retrieve contact details. Contact records can be retrieved based on the search criteria provided as filters in the request. An advertiser or agency can be associated with one or more contacts and vice-versa.

For more information about UAS Account & Admin Services APIs, refer to Account & Admin Services (UAS) 

Supported Operations

Service Name: /contacts/

                                             

Method PathHTTP Method TypeDescriptionLink to Definition
/contacts/POSTThis API method creates a contact as per provided information for your account.Create a Contact
/contacts/{id}GETRetrieve the details of a specific contact based on contact IDRetrieve Details for a Contact
/contacts/GET

This API method is used to retrieve all available contacts in your account.

Using this API, you can apply dimensions, filter criteria and sorting option to retrieve a list of records.

Retrieve a List of Contacts
/contacts/{id}PUT

Updates a single contact. This will be transactional.

  • This operation will do full update. If the request does not contain a value for an attribute, it will be either set to NULL or the default value. However, if the parameter is mandatory then it will fail and no contact will be updated.
  • Client must ensure that it is passing all the required attributes with required values.
  • The contact should not be Archived.
Update a Contact
/contacts/{id}PATCH

The API method performs a partial update on an object. e.g. To change the status of the contact then use partial update.

Currently, it can only update description and status of a given contact.

The contact should not be Archived.

NOTE: This is different than PUT. In PUT full replacement of the Object takes place.

Update (Patch) a Contact
/contacts/{id}DELETEThis API method is used for archiving the contacts. You cannot update any attribute value of a contact once it is archived.Delete a Contact

 

Create a Contact

 

Overview

This API enables you to create a contact.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                                                            

Parameter NameTypeRequiredValidationsDescriptions
accountNumericYes

Account must exist and be valid.

This is the account of the contact being created.

firstNameStringYesCan be a maximum of 255 characters.First Name of the Contact
lastNameStringYesCan be a maximum of 255 characters.Last Name of the Contact
emailStringYesCan be a maximum of 255 characters and unique at the account level.Contact is unique based on email id
phoneStringNoShould contain only digits, + or -Contact's phone number
streetAddress1StringNoCan be a maximum of 1024 charactersFirst line of the street address of the contact
streetAddress2StringNoCan be a maximum of 1024 charactersSecond line of the street address of the contact
cityStringNoCan be a maximum of 255 charactersCity of the contact
stateStringNoCan be a maximum of 255 charactersState of the contact
regionStringNoCan be a maximum of 255 charactersRegion of the contact
countryStringNoCan be a maximum of 255 charactersCountry of the contact
zipCodeStringNoCan be a maximum of 32 characters.Zip code of the contact
advertisersArray of Advertiser ObjectsNoShould contain a valid list of advertisers that exist in the system.Can associate a contact with one or more Advertisers
agenciesArray of Agency ObjectsNoShould contain a valid list of agencies that exist in the system.Can associate a contact with one or more Agencies

Sample Request URL

https://api.pubmatic.com/v1/uas/contacts/ 

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
    "advertisers": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "agencies": [
        {
            "id": 2
        }
    ]
}

Response

Sample Response JSON

    

{
    "id": 31,
    "account": {
        "id": 118385,
        "url": "http://$URI_PREFIX/phoenix/accounts/118385"
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
    "advertisers": [
                {
                    "id": 1
                },
                {
                    "id": 2
                }
    ],
    "agencies": [
            {
                "id": 2
            }
    ]
}

 

Retrieve Details for a Contact

 

Overview

This API enables you to create a contact.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/contacts/31

Response

Sample Response JSON

    

{
    "id": 31,
    "account": {
        "id": 118385,
        "url": "http://$URI_PREFIX/phoenix/accounts/118385"
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "Test-FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
     "advertisers": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "agencies": [
        {
            "id": 2
        }
    ]
}

 

Retrieve a List of Contacts

 

Overview

This API enables you to retrieve a list of all available contacts for your account. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Contacts with a specific set of details according to your requirements.

Refer to Common Request Query Parameters for more information about using dimensions, filters and sorting, 

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/contacts/ 

Response

Sample Response

    

The API will retrieve a list of all contacts associated with your account.

 

Update a Contact

 

Overview

This API enables you to update a contact. This is a full replacement of a contact upon update.

Request

           

URIHTTP Method
https://api.pubmatic.com/v1/uas/contacts/{contact id}PUT

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                                                            

Parameter NameTypeRequiredValidationsDescriptions
accountNumericYes

Account must exist and be valid.

This is the account of the contact being created.

firstNameStringYesCan be a maximum of 255 characters.First Name of the Contact
lastNameStringYesCan be a maximum of 255 characters.Last Name of the Contact
emailStringYesCan be a maximum of 255 characters and unique at the account level.Contact is unique based on email id
phoneStringNoShould contain only digits, + or -Contact's phone number
streetAddress1StringNoCan be a maximum of 1024 charactersFirst line of the street address of the contact
streetAddress2StringNoCan be a maximum of 1024 charactersSecond line of the street address of the contact
cityStringNoCan be a maximum of 255 charactersCity of the contact
stateStringNoCan be a maximum of 255 charactersState of the contact
regionStringNoCan be a maximum of 255 charactersRegion of the contact
countryStringNoCan be a maximum of 255 charactersCountry of the contact
zipCodeStringNoCan be a maximum of 32 characters.Zip code of the contact
advertisersArray of Advertiser ObjectsNoShould contain a valid list of advertisers that exist in the system.Can associate a contact with one or more Advertisers
agenciesArray of Agency ObjectsNoShould contain a valid list of agencies that exist in the system.Can associate a contact with one or more Agencies

Sample Request URL

https://api.pubmatic.com/v1/uas/contacts/31

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "Test-FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
    "advertisers": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "agencies": [
        {
            "id": 2
        }
    ]
}

Response

Sample Response JSON

    

{
    "id": 31,
    "account": {
        "id": 118385,
        "url": "http://$URI_PREFIX/phoenix/accounts/118385"
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "Test-FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
    "advertisers": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "agencies": [
        {
            "id": 2
        }
    ]
}

 

Update (Patch) a Contact

Overview

This API enables you to updates a contact. This is a full replacement of a contact upon update.

 

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                                                            

Parameter NameTypeRequiredValidationsDescriptions
accountNumericYes

Account must exist and be valid.

This is the account of the contact being created.

firstNameStringYesCan be a maximum of 255 characters.First Name of the Contact
lastNameStringYesCan be a maximum of 255 characters.Last Name of the Contact
emailStringYesCan be a maximum of 255 characters and unique at the account level.Contact is unique based on email id
phoneStringNoShould contain only digits, + or -Contact's phone number
streetAddress1StringNoCan be a maximum of 1024 charactersFirst line of the street address of the contact
streetAddress2StringNoCan be a maximum of 1024 charactersSecond line of the street address of the contact
cityStringNoCan be a maximum of 255 charactersCity of the contact
stateStringNoCan be a maximum of 255 charactersState of the contact
regionStringNoCan be a maximum of 255 charactersRegion of the contact
countryStringNoCan be a maximum of 255 charactersCountry of the contact
zipCodeStringNoCan be a maximum of 32 characters.Zip code of the contact
advertisersArray of Advertiser ObjectsNoShould contain a valid list of advertisers that exist in the system.Can associate a contact with one or more Advertisers
agenciesArray of Agency ObjectsNoShould contain a valid list of agencies that exist in the system.Can associate a contact with one or more Agencies

Sample Request URL

https://api.pubmatic.com/v1/uas/contacts/31

Sample Request JSON

    


{
    "account": {
        "id": 118385
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "Test-FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
    "advertisers": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "agencies": [
        {
            "id": 2
        }
    ]
}

Response

Sample Response JSON

    

{
    "id": 31,
    "account": {
        "id": 118385,
        "url": "http://$URI_PREFIX/phoenix/accounts/118385"
    },
    "email": "Test@pubmatic.com",
    "phone": "1234567890",
    "firstName": "Test-FirstName",
    "lastName": "LastName",
    "streetAddress1": "Test-Address1",
    "streetAddress2": "Tests-Addess2",
    "state": "Test-State",
    "region": "Test-Region",
    "country": "Test-Country",
    "zipCode": "123456",
    "advertisers": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "agencies": [
        {
            "id": 2
        }
    ]
}

 

Delete a Contact

Overview

This API enables you to delete (archive) a Contact.

 

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/contacts/31 

Response

Sample Response

    

Returns 'true' if archive is successful; 'false' if unsuccessful.

 

Error Codes For Contact

                          

Sr. No
Error Codes
Description

1.

PH_MISSING_OR_INVALID_PARAMETER

This error message will occur when a mandatory parameter is missing or the request is invalid.

It can occur for the following parameters:

  1. Account Id
  2. Email
  3. First Name
  4. Last Name
  5. Phone
 2.

PH_DUPLICATE_ENTITY

This error message will occur if the system finds duplicate information in the contact Request.

It can occur in the Email parameter.

3.PH_PARAMETER_VALUE_TOO_LARGE

This error message occurs when a parameter contains a value exceeding its allowed limit.

It can occur in following parameters:

  1. Contact Id
  2. Email
  3. Phone
  4. First Name
  5. Last Name
  6. Account
  7. street address 1
  8. street address 2
  9. city
  10. state
  11. region
  12. country
  13. zip code
4.PH_ATTEMPT_TO_UPDATE_RESTRICTED_FIELD_IN_STATUSThis error message occurs when a user tries to update an Archived contact using PUT/PATCH.

 

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

 

 

 

Version 17

Attachments

    Outcomes