Table Of Contents

Previous topic

Account Management

Next topic

PAAccount

ContactManagement

This APS type represents the platform built-in Contact Management Service that exposes some operations to get data necessary for operating account contacts. The considered APS type operates contact primitives like countries, ZIP codes, and other.

GraphViz

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "ContactManagement",
  "id": "http://www.parallels.com/pa/pa-core-services/contact-management/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "initialize": {
      "path": "contact/initialize",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "countries": {
      "path": "contact/countries",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "Country"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "zipLookup": {
      "path": "contact/zipLookup",
      "verb": "GET",
      "response": {
        "type": "ZipCodeResult"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "country": {
          "kind": "query",
          "type": "string"
        },
        "zip": {
          "kind": "query",
          "type": "string"
        }
      }
    },
    "hideWelcome": {
      "path": "welcome/hide",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    }
  },
  "structures": {
    "Country": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "ZipCodeResult": {
      "type": "object",
      "properties": {
        "countryCode": {
          "type": "string"
        },
        "postalCode": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "stateCode": {
          "type": "string"
        },
        "adminName2": {
          "type": "string"
        },
        "adminCode2": {
          "type": "string"
        },
        "adminName3": {
          "type": "string"
        },
        "adminCode3": {
          "type": "string"
        },
        "latitude": {
          "type": "string"
        },
        "longitude": {
          "type": "string"
        },
        "accuracy": {
          "type": "string"
        }
      }
    }
  }
}

The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:

POST  /aps/2/services/contact-manager/<operation-path>?<query-params>

{/*<body params>*/}

In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.

Custom Operations

OPERATION

VERB

PATH

RETURNS

Description

countries

GET

/contact/countries

If successful, returns a list of Country structures in the response body.

The contact/countries custom operation is used to get a list of countries available in the platform. For each country, it returns the country ID, name, and a list of states/provinces if the latter exist.

zipLookup

GET

/contact/zipLookup

If successful, returns a list of ZipCodeResult structures in the response body.

The contact/zipLookup?country={country-code}&zip={zipCode} custom operation finds the geographical location by country code and zip code. For example, GET /aps/2/resources/36a90fde-85a3-4ce0-b6cb-d934dd3704eb/contact/zipLookup?country=US&zip=64114.

countries

HTTP Request

GET /aps/2/services/contact-manager/contact/countries

Description

The contact/countries custom operation is used to get a list of countries available in the platform. For each country, it returns the country ID, name, and a list of states/provinces if the latter exist.

Returns

If successful, returns a list of Country structures in the response body.

zipLookup

HTTP Request

GET /aps/2/services/contact-manager/contact/zipLookup

Description

The contact/zipLookup?country={country-code}&zip={zipCode} custom operation finds the geographical location by country code and zip code. For example, GET /aps/2/resources/36a90fde-85a3-4ce0-b6cb-d934dd3704eb/contact/zipLookup?country=US&zip=64114.

Parameters

PARAMETER

TYPE

DESCRIPTION

country

String

Country code

zip

String

Zip code

Returns

If successful, returns a list of ZipCodeResult structures in the response body.

Structures

Country

Country.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

String

Not Required

Country code.

name

String

Not Required

Country name.

ZipCodeResult

The structure contains geographical data returned by the zipLookup operation.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

countryCode

String

Not Required

Country code.

postalCode

String

Not Required

Postal code.

city

String

Not Required

City..

state

String

Not Required

State..

stateCode

String

Not Required

State Code.

adminName2

String

Not Required

Admin Name 2.

adminCode2

String

Not Required

Admin Code 2.

adminName3

String

Not Required

Admin Name 3.

adminCode3

String

Not Required

Admin Code 3.

latitude

String

Not Required

Latitude..

longitude

String

Not Required

Longitude..

accuracy

String

Not Required

Accuracy..

Examples

Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.