API:people/import

From wiki.groundcrew.us

Imports agent data into your Groundcrew squad, either creating new agent entries or updating existing entries. Existing agents will only be updated if they are part of your squad. The import data can be formatted as either a JSON array parameter or a CSV file upload.

[edit] URL

 http://wwww.groundcrew.us/api/squad/{squad_id}/people/import.json

[edit] HTTP Method(s)

POST

[edit] Parameters

Required	Name	Type	Description
required	api_key	string	The authentication key associated with an organization.
	json*	string	A JSON array of hashes of agent information.
	csv_file*	file	A CSV file of agent information.
optional	exid_prefix	string	The name of the system used to generate the import data (e.g. 'salsa' or 'salesforce'). If exids are provided for any of the agents, this parameter must also be supplied; otherwise, it must not be supplied. This value must only contain alphanumeric characters (a-z, A-Z, 0-9).
	aggregate	string	If yes, all the imported agents will be aggregated into groups based on their location. Currently, they will be aggregated by country code and postcode. Aggregates appear on the map with a count of the agents incorporated in them, and the individual agents do not show up on the map. Aggregating is useful for importing large numbers of agents or agents who do not have detailed locations. Defaults to no.

* Exactly one of these parameters is required.

[edit] Agent Format

Variable names for agent import data structures:

Required	Name	Description
required	name	The name of the agent. Required only for new agents.
	phone	The mobile phone number for the agent. Required only for new agents.
	loc	An address or geographic point for the agent, which will be geocoded for that agent's base location. Required only for new agents. Not required if postcode is supplied instead.
	postcode	The postcode or zipcode for the agent. Required only if aggregating agents.
	cc2	The two-letter country code for the agent's home country. Required only if aggregating agents.
optional	id	The Groundcrew internal ID for the agent.
	exid	A unique identifier for the agent in the system that generated this import file. This id will only be used if the external system name (exid_prefix) is provided as a parameter to the API method. This value must only contain alphanumeric characters (a-z, A-Z, 0-9).
	email	An email address for the agent.
	tags	A space-delimited list of tags for the agent. Each tag must match this regex: /[\w._\/\-:]+/
	bio	A description of or notes about the user.
	url	The agent's homepage.
	image_url	The absolute URL to an image (of any size) representing the agent.
	thumb_url	The absolute URL to a small image (around 100px by 100px) representing the agent.
	row_prov	The provenance of this data. Defaults to a value based on exid_prefix.

[edit] Default values

Default values may be supplied for many of these variables by prefixing the variable name with default_. For example, default_name will set the name of the agent to the given value only if the agent does not already have a name in Groundcrew.

Parameters that support defaults include:
name, loc, cc2, bio, url, image_url, and thumb_url.

[edit] Data structures

Two data structures are currently supported:

[edit] CSV File

The first row in the file should be a header row with the above variable names.

[edit] JSON Array

An array of hashes. Each hash should include some of the above variable names.

[edit] Response

Returns HTTP status code 200 on success, and a JSON string in the body. The body is a hash, which includes a count of agents imported and an array of agents that could not be imported.

Example JSON response:

{
  "import_count": 29,
  "failed": [{"i": 17, "error": "no phone number available"}]
}

On failure, a non-200 status code will be returned, possibly with error information in JSON format as the response’s content.

[edit] Example

curl -d "api_key={key}" --data-urlencode "json=[{\"name\":\"Noah\",\"loc\":\"01060\",\"phone\":\"8001234567\"}]" \
http://wwww.groundcrew.us/api/squad/{squad_id}/people/import.json

curl -F "api_key={key}&csv_file=@{path/to/file.csv}" \
http://wwww.groundcrew.us/api/squad/{squad_id}/people/import.json