Contents

Contacts

Brands need to keep up with their customers, whether those customers have scheduled a session or purchased the photos of a family member. They do this by managing contacts. Contacts can be attached to events, contracts, invoices, and more.

List a brand’s contacts

get
/studio/brand/{brandId}/contact

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.

Query Parameters

Property Description
filterAllBrands
boolean

Return all contacts across all brands for the studio.
filterBrandId
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

Filters a collection by brand identifier.
filterEventId
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

Filters a collection by event identifier.
filterTag
string[]

Filter contacts by those having all of the given tags.
page
integer
  • default 1

The page of results to return.
rows
integer
  • default 25

The number of rows to return on each page of results.
searchContactInfo
string
  • ≤ 100 characters

Search contacts by name or email address, with partial matching.
searchEmail
string
email
  • ≤ 100 characters

Search contacts by email address, with exact matching.
sortBy
string
  • default "created"

Sort items in the collection by the given property.
sortType
string
enum
  • asc
  • desc
  • default "desc"

The direction in which sorting should occur.

Header Parameters

Property Description
Accept
string
enum
  • application/vnd.shootproof+json
  • text/csv

You may specify an Accept header to change the type of response, using content negotiation.
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A collection of brand contacts.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items
contact[]
Contact

A collection of resources returned in the current result set.

Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
birthDateDisplay read-only
string
date

The date on which this contact was born, properly formatted according to the brand’s locale.
brandId write-only deprecated
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

When creating a contact, a brandId may be provided to create the contact under a different brand.

This is deprecated in favor of using the other brand's contact collection resource to create contacts for the brand.
businessName nullable
string

The name for the business with which this contact is associated.
created read-only
string
date-time

The date on which this contact was created
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
refereeContacts read-only
contact[]
Contact Minimal

Contacts that have been referred by this contact.
referringContact nullable read-only
contact
Contact Minimal

The contact who referred this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
resourceCounts read-only
object
Property Description
numContracts
integer

The number of contracts with which this contact is associated.
numEvents
integer

The number of events with which this contact is associated.
numInvoices
integer

The number of invoices with which this contact is associated.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
meta read-only
object

Metadata describing the current result set.

Property Description
currentPage
integer

The current page of results returned.
rows
integer

The number of rows returned per page for the current result set.
totalItems
integer

The total number of items in the result set. This may be affected by active search/filter parameters.
totalPages
integer

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).
type
string
enum
  • contact-collection
Type

The type of resource represented.
Alternate Response Body

When the Content-Type of the response is text/csv, the following properties will be available in the response body.

Properties
string
Comma-separated values
Example Response
"\"Contact ID\",Brand,\"First Name\",\"Last Name\",Name,Email,Phone,Business,\"Contact Third Party ID\",Birthday,Tags,Created,\"Address 1\",\"Address 2\",City,State,ZIP/postal,Country,\"Referred By\",\"Referred Contacts\",Galleries\n\"0cc2ff9f-7c7a-418f-bf1b-bfbfde277a0e\",\"Jones Photography\",Jane,Doe,\"Jane Doe\",jdoe@example.com,123-456-7890,\"Acme, Inc.\",\"AwABAgkOAQIDCgIABA8MCw\",1971-06-08,\"Customer, Vendor\",2016-06-13T21:51:07+00:00,\"123 Any St\",\"Suite 102\",Anytown,GA,30039,US,\"John Doe\",\"Helen Doe, Jake Smith\",\"Doe Wedding, Jim Doe Graduation\""

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/ContactCollection"
        }
      },
      "text/csv": {
        "example": "\"Contact ID\",Brand,\"First Name\",\"Last Name\",Name,Email,Phone,Business,\"Contact Third Party ID\",Birthday,Tags,Created,\"Address 1\",\"Address 2\",City,State,ZIP/postal,Country,\"Referred By\",\"Referred Contacts\",Galleries\n\"0cc2ff9f-7c7a-418f-bf1b-bfbfde277a0e\",\"Jones Photography\",Jane,Doe,\"Jane Doe\",jdoe@example.com,123-456-7890,\"Acme, Inc.\",\"AwABAgkOAQIDCgIABA8MCw\",1971-06-08,\"Customer, Vendor\",2016-06-13T21:51:07+00:00,\"123 Any St\",\"Suite 102\",Anytown,GA,30039,US,\"John Doe\",\"Helen Doe, Jake Smith\",\"Doe Wedding, Jim Doe Graduation\"",
        "schema": {
          "title": "Comma-separated values",
          "type": "string"
        }
      }
    },
    "description": "A collection of brand contacts."
  }
}

Create a contact

post
/studio/brand/{brandId}/contact

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

application/vnd.shootproof+json
Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
brandId write-only deprecated
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

When creating a contact, a brandId may be provided to create the contact under a different brand.

This is deprecated in favor of using the other brand's contact collection resource to create contacts for the brand.
businessName nullable
string

The name for the business with which this contact is associated.
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/Contact"
      }
    }
  }
}

201 Created

The new contact.

Headers
Header Description
Location
string
uri

The URL new contact.
Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
birthDateDisplay read-only
string
date

The date on which this contact was born, properly formatted according to the brand’s locale.
businessName nullable
string

The name for the business with which this contact is associated.
created read-only
string
date-time

The date on which this contact was created
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
refereeContacts read-only
contact[]
Contact Minimal

Contacts that have been referred by this contact.
referringContact nullable read-only
contact
Contact Minimal

The contact who referred this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
resourceCounts read-only
object
Property Description
numContracts
integer

The number of contracts with which this contact is associated.
numEvents
integer

The number of events with which this contact is associated.
numInvoices
integer

The number of invoices with which this contact is associated.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
errors
object

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.
Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "201": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "The new contact.",
    "headers": {
      "Location": {
        "description": "The URL new contact.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

List tags that may be applied to contacts

get
/studio/brand/{brandId}/contact/tag

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.

Query Parameters

Property Description
searchTagName
string

Search contact tags, with partial matching.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A list of tags for contacts.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items
contact-tag[]
Contact Tag

A collection of resources returned in the current result set.

Property Description
isInUse
boolean

Whether this tag is currently applied to any contacts.
name
string

The contact tag name.
type
string
enum
  • contact-tag
Type

The type of resource represented.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
meta read-only
object

Metadata describing the current result set.

Property Description
currentPage
integer

The current page of results returned.
rows
integer

The number of rows returned per page for the current result set.
totalItems
integer

The total number of items in the result set. This may be affected by active search/filter parameters.
totalPages
integer

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).
type
string
enum
  • contact-tag-collection
Type

The type of resource represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.
Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/List"
            },
            {
              "properties": {
                "items": {
                  "items": {
                    "properties": {
                      "isInUse": {
                        "description": "Whether this tag is currently applied to any contacts.",
                        "type": "boolean"
                      },
                      "name": {
                        "description": "The contact tag name.",
                        "example": "Event Coordinator",
                        "type": "string"
                      },
                      "type": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/Type"
                          },
                          {
                            "enum": [
                              "contact-tag"
                            ]
                          }
                        ]
                      }
                    },
                    "title": "Contact Tag",
                    "type": "object"
                  },
                  "title": "Contact Tag",
                  "type": "array"
                },
                "type": {
                  "enum": [
                    "contact-tag-collection"
                  ]
                }
              },
              "title": "Collection of Contact Tags"
            }
          ]
        }
      }
    },
    "description": "A list of tags for contacts."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Delete a contact

delete
/studio/brand/{brandId}/contact/{contactId}

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.
contactId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The contact identifier.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

204 No Content

The resource was successfully deleted.

409 Conflict

If the the contact is linked to an invoice or contract, then we will respond with a 409 Conflict response.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.
Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "204": {
    "$ref": "#/components/responses/deleteSuccess"
  },
  "409": {
    "content": {
      "application/problem+json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "description": "If the the contact is linked to an invoice or contract, then we will\nrespond with a `409 Conflict` response."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Get a contact

get
/studio/brand/{brandId}/contact/{contactId}

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.
contactId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The contact identifier.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
birthDateDisplay read-only
string
date

The date on which this contact was born, properly formatted according to the brand’s locale.
businessName nullable
string

The name for the business with which this contact is associated.
created read-only
string
date-time

The date on which this contact was created
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
refereeContacts read-only
contact[]
Contact Minimal

Contacts that have been referred by this contact.
referringContact nullable read-only
contact
Contact Minimal

The contact who referred this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
resourceCounts read-only
object
Property Description
numContracts
integer

The number of contracts with which this contact is associated.
numEvents
integer

The number of events with which this contact is associated.
numInvoices
integer

The number of invoices with which this contact is associated.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.
Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "A contact."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Update a contact

put
/studio/brand/{brandId}/contact/{contactId}

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.
contactId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The contact identifier.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

A contact.

application/vnd.shootproof+json
Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
brandId write-only deprecated
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

When creating a contact, a brandId may be provided to create the contact under a different brand.

This is deprecated in favor of using the other brand's contact collection resource to create contacts for the brand.
businessName nullable
string

The name for the business with which this contact is associated.
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/Contact"
      }
    }
  },
  "description": "A contact.",
  "required": true
}

200 OK

The updated contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
birthDateDisplay read-only
string
date

The date on which this contact was born, properly formatted according to the brand’s locale.
businessName nullable
string

The name for the business with which this contact is associated.
created read-only
string
date-time

The date on which this contact was created
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
refereeContacts read-only
contact[]
Contact Minimal

Contacts that have been referred by this contact.
referringContact nullable read-only
contact
Contact Minimal

The contact who referred this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
resourceCounts read-only
object
Property Description
numContracts
integer

The number of contracts with which this contact is associated.
numEvents
integer

The number of events with which this contact is associated.
numInvoices
integer

The number of invoices with which this contact is associated.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
errors
object

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.
Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "The updated contact."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Send an email message to a contact

post
/studio/brand/{brandId}/contact/{contactId}/email

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.
contactId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The contact identifier.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

application/vnd.shootproof+json
Property Description
body
string
  • ≤ 10000 characters

The message to include in the body of the email.
headline
string
  • ≤ 100 characters

The headline to use in the email body.
subject
string
  • ≤ 200 characters

The subject line for the email message.
type
string
enum
  • email
Type

The type of resource represented.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "allOf": [
          {
            "properties": {
              "buttonText": {
                "readOnly": true
              },
              "recipientEmails": {
                "readOnly": true
              }
            }
          },
          {
            "$ref": "#/components/schemas/StudioToClientEmail"
          }
        ]
      }
    }
  },
  "required": true
}

202 Accepted

On success, we respond with the contact to whom the email message was sent.

Headers
Header Description
Content-Location
string
uri

The URL to the contact that is located in the response body.
Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable
address
Address

The address for this contact.
birthDate nullable
string
date

The date on which this contact was born.
birthDateDisplay read-only
string
date

The date on which this contact was born, properly formatted according to the brand’s locale.
businessName nullable
string

The name for the business with which this contact is associated.
created read-only
string
date-time

The date on which this contact was created
email
string
email

The email address for this contact.
firstName nullable
string

The first name for this contact.
id
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
lastName nullable
string

The last name for this contact.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
name nullable
string

The full name for this contact.
notes nullable
string

Notes made by the studio about this contact.
phone nullable
either
string
or
integer

The phone number for this contact.
refereeContacts read-only
contact[]
Contact Minimal

Contacts that have been referred by this contact.
referringContact nullable read-only
contact
Contact Minimal

The contact who referred this contact.
referringContactId nullable
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The identifier for the contact who referred this contact.
resourceCounts read-only
object
Property Description
numContracts
integer

The number of contracts with which this contact is associated.
numEvents
integer

The number of events with which this contact is associated.
numInvoices
integer

The number of invoices with which this contact is associated.
tags
string[]
unique

Tags describing this contact.
thirdPartyId nullable
either
integer
or
string

The identifier for this contact in the source system from which it originated.
type
string
enum
  • contact
Type

The type of resource represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
errors
object

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "202": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "On success, we respond with the contact to whom the email message was\nsent.",
    "headers": {
      "Content-Location": {
        "description": "The URL to the contact that is located in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

List recent activity for a contact

get
/studio/brand/{brandId}/contact/{contactId}/recent-activity

Example Request

Path Parameters

Property Description
brandId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The brand identifier.
contactId required
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

The contact identifier.

Header Parameters

Property Description
Authentication required
string

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A list of recent activity for a contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items
contact-recent-activity[]
Contact Recent Activity

A collection of resources returned in the current result set.

Property Description
activityDate nullable
string
date-time

The date on which this activity took place.
activityType
string

Human-readable description of the type of activity.
customInvoiceId nullable
integer

Identifier of the custom invoice related to this activity.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
relevantId
either
string
uuid
UUID Entity Identifier
or
integer
Integer Entity Identifier

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.
type
string
enum
  • contact-recent-activity
Type

The type of resource represented.
links required read-only
object
Links

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.
meta read-only
object

Metadata describing the current result set.

Property Description
currentPage
integer

The current page of results returned.
rows
integer

The number of rows returned per page for the current result set.
totalItems
integer

The total number of items in the result set. This may be affected by active search/filter parameters.
totalPages
integer

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).
type
string
enum
  • contact-recent-activity-collection
Type

The type of resource represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail
string

A longer description of of the error encountered.
info
object

Additional information that may be provided to aid in error resolution.

Property Description
reason
string
enum
  • contract-not-ready-to-countersign
  • event-photo-count-limit
  • plan-does-not-allow-uploads

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status
integer

The HTTP status code associated with this error.
title
string

A short description of the error encountered.
type
string
uri

A namespace URI uniquely identifying the error type.
Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/ContactRecentActivityCollection"
        }
      }
    },
    "description": "A list of recent activity for a contact."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}