@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Twilio SendGrid Marketing Campaigns Contacts API
@base https://api.sendgrid.com
@version 1.0.0
@auth Bearer bearer
@endpoints 15
@toc marketing(15)

@endpoint PUT /v3/marketing/contacts
@required {contacts: [map{address_line_1: str, address_line_2: str, alternate_emails: [str], city: str, country: str, email: str, phone_number_id: str, external_id: str, anonymous_id: str, first_name: str, last_name: str, postal_code: str, state_province_region: str, custom_fields: map}]}
@optional {list_ids: [str(uuid)]}
@returns(202) {job_id: str}
@errors {400, 401, 403, 404, 500}

@endpoint DELETE /v3/marketing/contacts
@optional {delete_all_contacts: str, ids: str}
@returns(202) {job_id: map}
@errors {400, 401, 403, 404, 500}

@endpoint GET /v3/marketing/contacts
@returns(200) {result: [map], _metadata: map{self: str}, contact_count: int}
@errors {400, 401, 403, 404, 500}

@endpoint GET /v3/marketing/contacts/{id}
@returns(200) {id: str, first_name: str, last_name: str, unique_name: str, email: str, phone_number_id: str, external_id: str, anonymous_id: str, alternate_emails: [str], address_line_1: str, address_line_2: str, city: str, state_province_region: str, country: str, postal_code: str, phone_number: str, whatsapp: str, line: str, facebook: str, list_ids: [str], segment_ids: [str], custom_fields: map, created_at: str, updated_at: str, _metadata: map{self: str}}
@errors {401, 403, 404, 500}

@endpoint POST /v3/marketing/contacts/batch
@required {ids: [str]}
@returns(200) {result: [map]}
@errors {401, 403, 404, 500}

@endpoint DELETE /v3/marketing/contacts/{contact_id}/identifiers
@required {contact_id: str, identifier_type: str(EMAIL/PHONENUMBERID/EXTERNALID/ANONYMOUSID), identifier_value: str}
@returns(202) {job_id: map}
@errors {400, 401, 403, 404, 500}

@endpoint GET /v3/marketing/contacts/count
@returns(200) {contact_count: int, billable_count: int, billable_breakdown: map{total: int, breakdown: map}}
@errors {401, 403, 404, 500}

@endpoint POST /v3/marketing/contacts/exports
@optional {list_ids: [str(uuid)], segment_ids: [str], notifications: map{email: bool}, file_type: str(csv/json), max_file_size: int=5000}
@returns(202) {_metadata: map{prev: str(uri), self: str(uri), next: str(uri), count: num}, id: str}
@errors {400, 401, 403, 404, 500}

@endpoint GET /v3/marketing/contacts/exports
@returns(200) {result: [map], _metadata: map{prev: str, self: str, next: str}}
@errors {400, 401, 403, 404, 500}

@endpoint GET /v3/marketing/contacts/exports/{id}
@returns(200) {id: str, status: str, created_at: str, updated_at: str, completed_at: str, expires_at: str, urls: [str], message: str, _metadata: map{prev: str(uri), self: str(uri), next: str(uri), count: num}, contact_count: int}
@errors {400, 401, 403, 404, 500}

@endpoint PUT /v3/marketing/contacts/imports
@required {file_type: str, field_mappings: [str]}
@optional {list_ids: [str]}
@returns(200) {job_id: str, upload_uri: str, upload_headers: [map]}
@errors {400, 401, 403, 404, 500}

@endpoint GET /v3/marketing/contacts/imports/{id}
@returns(200) {id: str, status: str, job_type: str, results: map{requested_count: num, created_count: num, updated_count: num, deleted_count: num, errored_count: num, errors_url: str}, started_at: str, finished_at: str}
@errors {400, 401, 403, 404, 500}

@endpoint POST /v3/marketing/contacts/search
@required {query: str}
@returns(200) {result: [map], _metadata: map{self: str}, contact_count: num}
@errors {400, 401, 403, 404, 408, 500}

@endpoint POST /v3/marketing/contacts/search/emails
@required {emails: [str]}
@optional {phone_number_id: str, external_id: str, anonymous_id: str}
@returns(200) {result: map}
@errors {400, 401, 403, 404, 500}

@endpoint POST /v3/marketing/contacts/search/identifiers/{identifier_type}
@required {identifiers: [str]}
@returns(200) {result: map}
@errors {400, 401, 403, 404, 500}

@end