# How can we help?
## Overview
The contact exports resource creates an export job to download and store a file of contacts from the Cordial database.
**API set name: contactexports**
### Additional information
- This resource uses the JSON request information to define the target host location of the file, the transport protocol, the external host login authentication information, and the fields to include in the file.
- It is important to note that this resource is not a collection of exports, but it is a resource that initiates export processing by creating an export job.
- Export status information is available through the Jobs resource. You can access the [Jobs page](https://support.cordial.com/hc/en-us/articles/14659667437453) via UI.
- Export supports file types CSV and JSON.
- Export files in the UI will be stored for 30 days from the date of the export.
## Authentication
Cordial's core APIs use https Basic Authentication (BA). From within the Cordial platform, you can generate an encoded [API key for your account](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.
- [Learn more about Cordial API authentication here](httpss://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication).
## Methods, parameters, and examples
- [POST/v2/contactexports](https://support.cordial.com/hc/en-us/articles/203886068-Contact-exports-API#postContactExports)
## POST/v2/contactexports
| Method | URL Path |
| --- | --- |
| POST | /v2/contactexports |
| Creates an export job using the JSON body information. |
- [Parameters](https://support.cordial.com/hc/en-us/articles/203886068-Contact-exports-API#zp-1-0)
- [Example JSON requests](https://support.cordial.com/hc/en-us/articles/203886068-Contact-exports-API#zp-1-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/203886068-Contact-exports-API#zp-1-2)
\* Required
| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| name | string | Defines the export file name. The name may only contain letters, numbers, and dashes. If provided, this value will be displayed next to the job ID on the Jobs Widget page. | contactsExport |
| exportType | string | Defines the type of file or report.
**Possible Values:** CSV, JSON | csv |
| fields | string | An array of system fields or contact attribute keys. | ["first_name","last_name"] |
| lists | array | An array of lists IDs or list names to be returned. Contacts' list association is indicated with a value of "1" if they are on the list or "0" if they are not on the list. | ["monthly_newsletter","weekly_specials"] or [8756,8757] |
| audience-key | string | Limits export results to a specific audience from a saved audience rule name. | 30_day_engaged |
| showHeader | string | Determines if the first row will display column names when export file type is CSV. The default is false.
**Possible Values:**
true, false | true |
| compress | boolean | Compresses the exported file. If value is "true", the file is compressed using GZIP with the file extension ".gz" added to the filename. | true |
| confirmEmail | email | Email address to send an administrative alert when the import job has been completed. | msmith@example.com |
| ### **\* destination**
This parameter is only required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is used as the destination. Destination type " **aws**" should be used if the file is to be downloaded via the UI. |
| type | string | Defines the destination type.
**PossibleValues**:
aws, ftp, sftp, s3, gcs | sftp |
| server
(required if type is FTP or SFTP) | string | Domain or IP address of the SFTP server. | sftp.example.com |
| username
(required if type is FTP or SFTP) | string | Defines the username for FTP or SFTP authentication. | username |
| password
(required if type is FTP or SFTP) | string | Defines the password for FTP or SFTP authentication. | password |
| savedKey
(if using SFTP public key authentication instead of password) | string | [SFTP public key authentication](https://support.cordial.com/hc/en-us/articles/360033230732) key name. | myKeyName |
| port
(required if type is FTP or SFTP) | number | Defines the port number for the FTP or SFTP server. | 22 |
| aws_access_key_id
(required if type is S3) | string | Defines the public AWS id. | A1234567890 |
| aws_secret_access_key
(required if type is S3) | string | Defines the secret AWS key. | B1234567890 |
| aws_bucket
(required if type is S3) | string | Defines the AWS bucket name. | bucketname |
| aws_region
(required if type is S3) | string | Defines the AWS region. | us-west-2 |
| path | string | If type is S3: path to folder and file. If type is FTP, SFTP, or GCS: path to folder. | S3: /folder/contactsExport.csv, FTP: /folder, GCS: /folder |
| gcs_bucket | string | Defines the GCS bucket name. | bucketname |
### Cordial UI
The following will initiate an export job of a CSV file containing all contacts and all fields, downloadable via the UI on the [Jobs page](https://support.cordial.com/hc/en-us/articles/115008871127).
```
{
"exportType": "csv",
"name": "contactExport",
"destination": {
"type": "aws"
},
"showHeader": true,
"confirmEmail": "msmith@example.com"
}
```
### FTP/SFTP
The following will initiate an export job of a CSV file via SFTP containing all contacts and two fields.
```
{
"exportType": "csv",
"name": "contactExport",
"destination": {
"type": "sftp",
"server": "example.com",
"port": "21",
"username": "username",
"password": "password",
"path": "/"
},
"showHeader": true,
"fields": [
"channels.email.address",
"first_name"
],
"confirmEmail": "msmith@example.com"
}
```
### Amazon S3
Amazon S3: The following will initiate an export job of all contacts in the "30_day_engaged" audience, 2 fields and 2 lists into a CSV file via Amazon S3. In this example, the file will be uploaded to `s3://my_bucket/folder`.
```
{
"exportType": "csv",
"name": "myExportFilename",
"destination": {
"type": "s3",
"aws_access_key_id": "A1234567890",
"aws_secret_access_key": "B1234567890",
"aws_bucket": "my_bucket",
"aws_region": "us-west-2",
"path": "folder"
},
"showHeader": true,
"audience-key": "30_day_engaged",
"fields": [
"channels.email.address",
"channels.email.subscribeStatus"
],
"lists": [
"monthly_newsletter",
"first_name"
],
"confirmEmail": "msmith@example.com"
}
```
We recommend omitting the trailing slash right after your S3 path name to avoid duplicate slashes being added by default. For example, use `folder` instead of `/folder/`.
### Google Cloud Storage
The following will initiate an export job of a CSV file of all contacts in the "engaged-march" audience via Google Cloud Storage (GCS).
Your [Google Could Storage integration](https://support.cordial.com/hc/en-us/articles/360018718571) must be enabled.
```
{
"exportType": "csv",
"name": "contactExport",
"destination": {
"type": "gcs",
"gcs_bucket": "bucketname",
"path": "/contactexports"
},
"showHeader": true,
"audience-key": "engaged-march",
"confirmEmail": "emsmith@example.com"
}
```
The following URL in conjunction with the JSON will perform the POST.
```
https:///v2/contactexports
```
**1.)** If no fields or lists parameters are passed (or passed with empty array values), **all** fields and lists will be returned in the file. **2.)** If the lists parameter is passed with array values, and no fields parameter is passed (or passed with empty array values), the email field and designated list values will be returned in the file.
## Test in Swagger
You can [access and test Cordial's APIs in Swagger](https://support.cordial.com/hc/en-us/articles/216197618).
## Error responses
The Cordial API will return an error object with an `errorKey` and `message` if there is a problem with an API call. You can find more detailed error responses on the [Global API error responses](https://support.cordial.com/hc/en-us/articles/4402427843597-Global-API-Error-Responses) page.