API Reference

Introduction

Welcome to the developer documentation for Project Map It. This API (Application Programming Interface) could be useful to you if you wish to do something such as:

Integrate and automate your projects from other CMS's or systems
Display or manage Project Map It data within an internal dashboard
Something else to make your job more efficient

We strive to make our system as flexible as possible and encourage you to reach out. Some reasons you want to contact us directly would be:

You'd like help discussing your strategy for integration
You're hitting limitations with the API
You have any other questions or feedback

Authentication

The Project Map It API uses tokens to authenticate requests. You can view and manage your API tokens in the Project Map It Developer Dashboard. API tokens are used to authorize a request using one of the two HTTP headers:

Authorization: Bearer your-api-token
Authorization: Basic your-api-token: (note the colon on the end)

You'll most likely use the Bearer token because it allows for cross-origin requests. We use the Basic protocol in the examples below because the syntax is simpler when making a curl request.

API Versions

Endpoints documented under /v3 are the current version of the API. Endpoints under /api/v1 are the legacy version: they remain fully supported, and existing integrations built against them do not need to change. Where an endpoint exists in both versions, the request and response formats are identical; the /v3 URL is simply the one we recommend for new integrations.

Error Handling

Project Map It uses conventional HTTP response codes to indicate the success or failure of an API request. A successful response will result in a 200. An unsuccessful response will result in a 4xx.

Along with a 4xx error code, an errors object will be returned which contains an array of one or more human-readable problems which occurred and a optional error code specific to the endpoint being requested.

{
    "code": 1000,
    "errors": [
        "Insufficient permissions"
    ]
}

Entity Types

Below are all of the various (JSON) object types which are returned by the Project Map It API.

Project Type

_idstring	The unique ID for the project.
statestring	This must be a valid state acronym such as "DC", "CA", or "NY".
citystring	Example: "San Francisco".
streetstring	Example: "Lombard Street".
street_detailsstring	Example: "2nd Floor".
zipstring	Example: "90210".
countrystring	Example: "US".
namestring	A name for this project. By default, this name is for internal identification and not shown to the public.
subnamestring	A secondary name for this project.
descriptionstring	A description for this project. Can be used to store additional information or notes about the project.
categoriesCategory[]	The categories applied to this project. When reading a project these are full category objects; when writing one, send an array of category IDs.
surveySurveyAnswer[]	This will only be provided if the survey has been completed. Otherwise, this field will be an empty array.
surveyNamesContactName[]	Contact names stored as a reference for this project.
surveyEmailsEmailAddress[]	The survey will be sent to these email addresses. A project can hold at most 3.
surveyPhoneNumbersPhoneNumber[]	A list of contact numbers to store as a reference for this project.
surveyFlagstring	Determines whether or not this project can receive emails related to the surveys. One of "subscribed", "unsubscribed", or "blacklisted".
surveySentDate	Date which the survey for this project was sent.
surveyCompletedDate	Date which the survey for this project was completed.
activeboolean	Determines whether or not this project is public.
typestring	Determines what type of portfolio the project belongs to. One of "project", "member", or "tournament".
photoCountnumber	Indicates how many photos this project has associated.
member_infoMemberInfo	Contains fields related to projects of type member.
tournament_infoTournamentInfo	Contains fields related to projects of type tournament.
photosFile[]	The project's photos, in display order. Returned when retrieving or listing projects.
createdDate	Date which the project was created.
updatedDate	Date which the project was last updated.

PhoneNumber Type

phonestring

A customer phone number for internal reference only.

EmailAddress Type

emailstring

A valid email address. If a survey is triggered, this is the email address which will be sent to.

ContactName Type

namestring

A contact name to store as a reference for this project.

SocialMedia Type

labelstring	The name of the network, for example "Facebook". Required.
urlstring	A link to the profile on that network.

SurveyAnswer Type

immutableboolean	A Project Map It system survey question which is guaranteed to be present for every project.
questionstring	The full question the customer was asked.
kindstring	One of "star", "boolean", or "text".
pubboolean	Determines whether or not this survey question is public.
answerstring	Star: "1", "2", "3", "4", or "5". Boolean: "1", "0". Text: "Customer input."

MemberInfo Type

phone_numbersPhoneNumber[]	A list of contact numbers to store as a reference for this customer.
emailsEmailAddress[]	A list of contact emails to store as a reference for this customer.
socialMediaSocialMedia[]	A list of social media links to store as a reference for this customer.
websitestring	The customer's website.

TournamentInfo Type

hoststring	The tournament's hosting facility.
phone_numbersPhoneNumber[]	A list of contact numbers to store as a reference for this tournament.
emailsEmailAddress[]	A list of contact emails to store as a reference for this tournament.
socialMediaSocialMedia[]	A list of social media links to store as a reference for this tournament.
websitestring	The tournament's website.
event_dateobject	The dates the tournament runs, as `{ event_start, event_end }`. Both are dates.
genderstring	The gender division the tournament belongs to. One of "Boys", "Girls", or "Mixed".
age_levelstring	The age level division the tournament belongs to. Example "High School", "Middle School".
divisionsstring	The division the tournament belongs to. Example "AAA", "AA", "A", "B".
vendor_registrationstring	The link to the tournament's registration vendor.
vendor_registration_labelstring	The text to display for the registration vendor link.

File Type

_idstring	The unique ID for the file.
organizationstring	ID of the organization the file belongs to.
referencestring	ID of the project which the file is associated to.
ordernumber	The file's position in the project's photo order. Lower numbers appear first.
createdDate	Date which record was created.
takenPicDateDate	Contains the Date on which the photo was taken. This will only be provided if the file it's an image. Otherwise, this field will match the creation date.
publishedBoolean	Determines whether or not this file is public.
original_filenamestring	The original name of the file. This will only be provided if the file it's an image and the name can be extracted from the file. Otherwise, this field will be null.
metaFileMeta	Contains the width and height of the file. This will only be provided if the file it's an image.
pathFilePath	Paths for file.

FileMeta Type

widthnumber	Width of image.
heightnumber	Height of image.

FilePath Type

smallstring	Full CDN URL to the thumbnail version of the file.
largestring	Full CDN URL to the full-size version of the file.
facebookstring	Full CDN URL to a preview version of the file sized for social sharing.

Category Type

_idstring	Category ID.
organizationstring	Organization ID.
parentstring	ID of the parent category.
namestring	Name of category.
createdDate	Date which record was created.
ordernumber	The category's position in your organization's category order. Lower numbers appear first.
disabledboolean	Determines whether or not the category is hidden from your public map.

Projects

Create a project

POST /v3/project

Legacy URL: POST /api/v1/project (still supported for existing integrations).

curl https://projectmapit.com/v3/project \
    -u your-api-key: \
      -H 'Content-Type: application/json' \
      -d '
    {
      "name": "Awesome Project!",
      "city": "San Francisco",
      "state": "CA",
      "street": "Lombard Street"
    }
    '

Arguments

statestring	required	This must be a valid state acronym such as "DC", "CA", or "NY".
citystring	required	Example: "San Francisco".
streetstring	required	Example: "Lombard Street".
street_detailsstring	optional	Example: "2nd Floor".
zipstring	optional	Example: "90210".
countrystring	optional	Example: "US".
namestring	optional	A name for this project. Defaults to "Untitled". By default, this name is for internal identification and not shown to the public.
subnamestring	optional	A secondary name for this project. Defaults to "Untitled".
descriptionstring	optional	A description for this project. Can be used to store additional information or notes about the project.
categoriesstring[]	optional	A set of category IDs to apply to this project.
surveyEmailsEmailAddress[]	optional	The survey will be sent to these email addresses if triggered. Otherwise, just used as internal reference.
surveyPhoneNumbersPhoneNumber[]	optional	A list of contact numbers to store as a reference for this project.
surveyNamesContactName[]	optional	Contact names to store as a reference for this project.
surveyFlagstring	optional	Determines whether or not this project can receive emails related to the surveys. One of "subscribed", "unsubscribed", or "blacklisted". Defaults to "subscribed".
member_infoMemberInfo	optional	Contains fields related to projects of type member.
tournament_infoTournamentInfo	optional	Contains fields related to projects of type tournament.

Response

A project object will be returned if successful. The longitude and latitude will be generated automatically upon creation.

Upsert a project

POST /v3/project/upsert

Legacy URL: POST /api/v1/project/upsert (still supported for existing integrations).

This is the recommended endpoint for partner integrations that sync projects from an external system. It creates the project if it doesn't exist yet, and updates the existing one when it does, so re-sending the same record is always safe and never creates a duplicate. The address is geocoded, and if another project of your organization already exists at the same normalized address, that project is updated instead of creating a new one.

When an existing project is updated, categories, surveyEmails, and surveyPhoneNumbers are merged with the existing values (union, no duplicates) rather than replaced.

curl https://projectmapit.com/v3/project/upsert \
    -u your-api-key: \
      -H 'Content-Type: application/json' \
      -d '
    {
      "name": "Awesome Project",
      "street": "H St. NE",
      "city": "Washington",
      "state": "DC",
      "country": "US"
    }
    '

Arguments

streetstring	required	Example: "H St. NE".
citystring	required	Example: "Washington".
statestring	required	This must be a valid state acronym such as "DC", "CA", or "NY".
countrystring	required	Example: "US". Note this differs from the create endpoint, where country defaults to "US".
zipstring	optional	Example: "90210".
namestring	optional	A name for this project. By default, this name is for internal identification and not shown to the public.
subnamestring	optional	A secondary name for this project.
descriptionstring	optional	A description for this project. Can be used to store additional information or notes about the project.
categoriesstring[]	optional	A set of category IDs to apply to this project. Merged with the existing categories when updating a matched project.
surveyEmailsEmailAddress[]	optional	The survey will be sent to these email addresses if triggered. Merged with the existing addresses when updating a matched project. A project can hold at most 3.
surveyPhoneNumbersPhoneNumber[]	optional	A list of contact numbers to store as a reference for this project. Merged with the existing numbers when updating a matched project.
surveyNamesContactName[]	optional	Contact names to store as a reference for this project.

Response

The created or updated project object is returned. If the required address fields are missing, a 400 is returned with the error "Missing required address fields.".

Import projects in bulk

POST /v3/projects

Legacy URL: POST /api/v1/projects (still supported for existing integrations).

This endpoint imports many projects at once. The projects are queued and created asynchronously in the background. A 200 response means the import was accepted, not that the projects exist yet.

Note: the request body must be a JSON object with a projects array. Sending a single project object at the top level is not an error, but there is nothing to import, so the request returns {"ok": 1} without creating anything. To create or sync one project at a time, use the create-project or upsert-project endpoint instead.

curl https://projectmapit.com/v3/projects \
    -u your-api-key: \
      -H 'Content-Type: application/json' \
      -d '
    {
      "projects": [
        {
          "name": "Awesome Project",
          "city": "Washington",
          "state": "DC",
          "street": "H St. NE"
        }
      ]
    }
    '

Arguments

projectsProjectInput[]	required	A collection of project input arguments. These are the same as the create-project endpoint.
updateboolean	optional	Defaults to `true`: a row whose address matches an existing project updates that project instead of creating a duplicate. When `false`, rows matching an existing project are skipped.

Response

Projects are created asynchronously.

oknumber

If successfully queued for import, ok will always be 1.

Retrieve a project

GET /v3/project/:projectId

Legacy URL: GET /api/v1/project/:projectId (still supported for existing integrations).

curl https://projectmapit.com/v3/project/:projectId \
  -u your-api-key:

Arguments

projectIdstring

required

ID of project.

Response

A project object will be returned if successful. The categories field contains full category objects rather than IDs, and the photos field contains the project's file objects in display order.

Update a project

PUT /v3/project/:projectId

Legacy URL: PUT /api/v1/project/:projectId (still supported for existing integrations).

curl -X PUT \
  https://projectmapit.com/v3/project/:projectId \
  -u your-api-key: \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "New Project Name",
    "city": "San Francisco",
    "state": "CA",
    "street": "Lombard Street"
  }
  '

The address is re-geocoded from the request body on every update, so street, city and state must be sent even when they have not changed. Any other field you omit is left as it is.

Arguments

statestring	required	This must be a valid state acronym such as "DC", "CA", or "NY".
citystring	required	Example: "San Francisco".
streetstring	required	Example: "Lombard Street".
street_detailsstring	optional	Example: "2nd Floor".
zipstring	optional	Example: "90210".
countrystring	optional	Example: "US".
namestring	optional	A name for this project. By default, this name is for internal identification and not shown to the public.
subnamestring	optional	A secondary name for this project.
descriptionstring	optional	A description for this project. Can be used to store additional information or notes about the project.
categoriesstring[]	optional	A set of category IDs to apply to this project.
surveySurveyAnswer[]	optional	The updated collection of survey answers. Warning: Any survey answers that aren't passed back will be removed.
surveyEmailsEmailAddress[]	optional	The survey will be sent to these email addresses if triggered. Otherwise, just used as internal reference.
surveyPhoneNumbersPhoneNumber[]	optional	A list of contact numbers to store as a reference for this project.
surveyNamesContactName[]	optional	Contact names to store as a reference for this project.
surveyFlagstring	optional	Determines whether or not this project can receive emails related to the surveys. One of "subscribed", "unsubscribed", or "blacklisted".
activeboolean	optional	Determines whether or not this project is public.
member_infoMemberInfo	optional	Contains fields related to projects of type member.
tournament_infoTournamentInfo	optional	Contains fields related to projects of type tournament.

Response

A project object will be returned if successful. The longitude and latitude are regenerated from the address on every update.

Delete a project

DELETE /v3/project/:projectId

Legacy URL: DELETE /api/v1/project/:projectId (still supported for existing integrations).

curl -X DELETE \
  https://projectmapit.com/v3/project/:projectId \
  -u your-api-key:

Arguments

projectIdstring

required

ID of project

Response

successnumber

The value will always be 1. Otherwise, an error object will be returned.

Upload project photo

POST /v3/project/:projectId/file/:publish

Legacy URL: POST /api/v1/project/:projectId/file/:publish (still supported for existing integrations).

curl https://projectmapit.com/v3/project/:projectId/file/true \
    -u your-api-key: \
    -F 'file[]=@/path/to/some-file.jpg' \
    -F 'file[]=@/path/to/some-file-2.jpg'

Arguments

:publishboolean	required	Path parameter controlling whether the uploaded photos are published to the public profile. Pass `true` to publish or `false` to upload without publishing.
file[]file	required	The file should follow the specifications of RFC 2388 (multipart/form-data protocol). Up to 5 files may be uploaded at a time, each up to 15MB. Supported formats are: jpeg, png, gif.

Response

oknumber

The value will always be 1 when submitted successfully.

Remove project photo

DELETE /v3/project/:projectId/file/:fileId

Legacy URL: DELETE /api/v1/project/:projectId/file/:fileId (still supported for existing integrations).

curl -X DELETE \
    https://projectmapit.com/v3/project/:projectId/file/:fileId \
    -u your-api-key:

Arguments

projectIdstring	required	The project's ID which the file is attached to.
fileIdstring	required	The file's ID.

Response

oknumber

The value will always be 1 when removed successfully.

Order project photos

PUT /v3/project/:projectId/file/order

Legacy URL: PUT /api/v1/project/:projectId/file/order (still supported for existing integrations).

curl -X PUT \
    https://projectmapit.com/v3/project/:projectId/file/order \
    -u your-api-key: \
    -H 'Content-Type: application/json' \
    -d '
    {
      "order": ["file-id-1", "file-id-2", "file-id-3"]
    }
    '

Every file you list is published as part of the reorder, so send only the photos you want visible on the public profile.

Arguments

orderstring[]

required

An array of file IDs in the order they should be in. The files must belong to the project named in the path.

Response

oknumber

The value will always be 1 when successful.

List all projects

GET /v3/projects?limit=5&page=1

Legacy URL: GET /api/v1/projects?limit=5&page=1 (still supported for existing integrations).

Returns a paginated list of the projects belonging to the organization that owns the API token.

curl https://projectmapit.com/v3/projects \
  -u your-api-key:

Arguments

sstring	optional	Query string argument. Any string which a full index search is performed on.
pagestring	optional	Query string argument. A page number which contains a max of the specified limit. Defaults to 1. Pass `-1` to return every matching project in a single unpaginated response.
limitstring	optional	Query string argument. Projects per page. Defaults to 5. The max is 100.
sortstring	optional	Query string argument. A JSON object of field names to `1` (ascending) or `-1` (descending), for example `{"name":1}`. Defaults to newest first by created date.
onlyPublishedPhotosboolean	optional	When set to any non-empty value, the `photos` array of each project only contains published photos. Omit it entirely to receive every photo.
filter flagsboolean	optional	Query string arguments. Each is applied only when set to the string `true`, and multiple flags may be combined. onlyPublished /onlyUnpublished - Restricts to projects that are, or are not, public. withPhotos /withoutPhotos - Restricts to projects that do, or do not, have photos. withPublishedPhotos /withoutPublishedPhotos - Restricts to projects that do, or do not, have published photos. withDescription /withoutDescription - Restricts to projects that do, or do not, have a description. withCategories /withoutCategories - Restricts to projects that do, or do not, have categories applied. withReviews /withoutReviews - Restricts to projects that do, or do not, have reviews.

Response

pagenumber	The current page.
pagesnumber	The total number of pages.
perPagenumber	The limit of projects per page.
totalCountnumber	The total number of projects matching the request, across all pages.
resultsProject[]	A collection of project objects. Each one includes its `categories` as full category objects and its `photos` as full file objects.

Send project survey

POST /v3/project/:projectId/send-survey

Legacy URL: POST /api/v1/project/:projectId/send-survey (still supported for existing integrations).

Sends the customer survey email for a project. By default it is sent to the addresses already stored on the project in surveyEmails.

curl -X POST \
    https://projectmapit.com/v3/project/:projectId/send-survey \
    -u your-api-key: \
    -H 'Content-Type: application/json' \
    -d '{}'

Arguments

projectIdstring	required	Path parameter. The ID of the project the survey belongs to.
commaDelimitedEmailsstring	optional	A comma-separated list of email addresses. When supplied, the survey is sent to these addresses instead of the ones stored on the project. The project's stored `surveyEmails` are not changed. If the project has no stored addresses and none are supplied here, an error is returned.

Response

oknumber

The value will always be 1 when sent successfully.

Create a category

POST /v3/category

Legacy URL: POST /api/v1/category (still supported for existing integrations).

Creates a category for your organization. Pass parent to create a subcategory of an existing category. New top-level categories are appended to the end of your category order.

curl https://projectmapit.com/v3/category \
  -u your-api-key: \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "Roofing"
  }
  '

Arguments

namestring	required	A name for the category. Maximum 60 characters.
parentstring	optional	The ID of the category this category belongs under. Omit it to create a top-level category.

Response

A category object will be returned if successful.

Retrieve a category

GET /v3/category/:categoryId

Legacy URL: GET /api/v1/category/:categoryId (still supported for existing integrations).

curl https://projectmapit.com/v3/category/:categoryId \
  -u your-api-key:

Arguments

categoryIdstring

required

The ID of the category. The category must belong to your organization.

Response

A category object will be returned if successful.

Update a category

PUT /v3/category/:categoryId

Legacy URL: PUT /api/v1/category/:categoryId (still supported for existing integrations).

Only the fields you send are changed. The category must belong to your organization.

curl -X PUT \
  https://projectmapit.com/v3/category/:categoryId \
  -u your-api-key: \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "New Category Name"
  }
  '

Arguments

categoryIdstring	required	Path parameter. The ID of the category to update.
namestring	optional	A name for the category. Maximum 60 characters.
parentstring	optional	The ID of the category this category belongs under.

Response

The full category object will be returned if successful.

Delete a category

DELETE /v3/category/:categoryId

Legacy URL: DELETE /api/v1/category/:categoryId (still supported for existing integrations).

Deleting a category also deletes its direct subcategories, and removes all of them from any project they were applied to. The projects themselves are not deleted.

curl -X DELETE \
  https://projectmapit.com/v3/category/:categoryId \
  -u your-api-key:

Arguments

categoryIdstring

required

Category ID.

Response

oknumber

The value will always be 1 when deleted successfully. Otherwise, an error object will be returned.

GET /v3/categories?out=:format

Legacy URL: GET /api/v1/categories?out=:format (still supported for existing integrations).

Returns every category belonging to the organization that owns the API token, sorted by parent, then order, then name.

curl https://projectmapit.com/v3/categories \
  -u your-api-key:

Arguments

outstring

optional

Query string argument. Allowed values:

flat - Returns a flat collection. This is the default.

nested - Returns a nested collection by parent hierarchy. Each category gains a children array, and only top-level categories appear at the root.

Response

resultsCategory[]

A collection of category objects.

Maps

List map embeds

GET /v3/embeds

curl https://projectmapit.com/v3/embeds \
  -u your-api-key:

Arguments

This endpoint takes no arguments. The embeds returned belong to the organization that owns the API token used to authenticate the request.

Response

Returns an embeds array. Each element describes one of the organization's saved map embeds, including a ready-to-paste HTML snippet.

embedsobject[]	A collection of map embed objects, each with the fields below.
embeds[].idstring	The saved map's unique id.
embeds[].labelstring	The saved map's display name.
embeds[].defaultboolean	Whether this is the organization's default map.
embeds[].embedCodestring	A ready-to-paste HTML/script snippet that renders this map on an external web page.

Users

Retrieve a user

GET /v3/current-user

Legacy URL: GET /api/v1/current-user (still supported for existing integrations).

Returns the account associated with the API token used to make the request. This endpoint requires the Bearer form of the Authorization header.

curl https://projectmapit.com/v3/current-user \
  -H 'Authorization: Bearer your-api-token'

Response

idstring	The user's unique ID.
namestring	The user's name.
emailstring	The user's email address.
phonestring	The user's phone number.
organizationobject	The organization the token belongs to, as `{ id, name }`.

API Reference

Introduction

Authentication

API Versions

Error Handling

Entity Types

Project Type

PhoneNumber Type

EmailAddress Type

ContactName Type

SocialMedia Type

SurveyAnswer Type

MemberInfo Type

TournamentInfo Type

File Type

FileMeta Type

FilePath Type

Category Type

Projects

Create a project

Arguments

Response

Upsert a project

Arguments

Response

Import projects in bulk

Arguments

Response

Retrieve a project

Arguments

Response

Update a project

Arguments

Response

Delete a project

Arguments

Response

Upload project photo

Arguments

Response

Remove project photo

Arguments

Response

Order project photos

Arguments

Response

List all projects

Arguments

Response

Send project survey

Arguments

Response

Categories

Create a category

Arguments

Response

Retrieve a category

Arguments

Response

Update a category

Arguments

Response

Delete a category

Arguments

Response

List all categories

Arguments

Response

Maps

List map embeds

Arguments

Response

Users

Retrieve a user

Response