API Resources

Announcements

class Announcements(session_kwargs, return_type='civis')

Methods

list(*[, limit, page_num, order, order_dir, ...]) List announcements
list(*, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List announcements

Parameters:

limit : integer, optional

Number of results to return. Defaults to 10. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to released_at. Must be one of: released_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of this announcement

subject : string

The subject of this announcement.

body : string

The body of this announcement.

released_at : string/date-time

The date and time this announcement was released.

created_at : string/date-time

updated_at : string/date-time

Apps

class Apps(session_kwargs, return_type='civis')

Methods

delete_instances_projects(id, project_id, slug) Remove a AppInstance from a project
delete_instances_shares_groups(id, group_id, ...) Revoke the permissions a group has on this object
delete_instances_shares_users(id, user_id, slug) Revoke the permissions a user has on this object
get(slug) List details of a Decision Application
get_instances(id, slug) Return a given app instance
list() List apps
list_instances(slug, *[, archived, ...]) List the instances of a Decision Application
list_instances_projects(id, slug, *[, hidden]) List the projects a AppInstance belongs to
list_instances_shares(id, slug) List users and groups permissioned on this object
patch_instances(id, slug, *[, name]) Update a given app instance
post_instances(slug, *[, name]) Create a new instance of an application of the given slug
put_instances_archive(id, slug, status) Update the archive status of this object
put_instances_projects(id, project_id, slug) Add a AppInstance to a project
put_instances_shares_groups(id, slug, ...[, ...]) Set the permissions groups has on this object
put_instances_shares_users(id, slug, ...[, ...]) Set the permissions users have on this object
delete_instances_projects(id, project_id, slug)

Remove a AppInstance from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

slug : string

The slug for the application.

Returns:

None

Response code 204: success

delete_instances_shares_groups(id, group_id, slug)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

slug : string

The slug for the application.

Returns:

None

Response code 204: success

delete_instances_shares_users(id, user_id, slug)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

slug : string

The slug for the application.

Returns:

None

Response code 204: success

get(slug)

List details of a Decision Application

Parameters:

slug : string

The slug for the application.

Returns:

slug : string

The slug for the application.

id : integer

The unique id of the application.

instance_name : string

A word that describes an instance of this app.

name : string

The name of the application.

current_release : dict:

- id : integer
    The unique id of the release.
- app_id : integer
    The id of the app the release belongs to.
- report_template_id : integer
    ID of the report template for this release.
- resources : dict
    A hash of resources associated with this release.

features : dict

App features.

get_instances(id, slug)

Return a given app instance

Parameters:

id : integer

The unique id of the instance.

slug : string

The slug for the application.

Returns:

id : integer

The unique id of the instance.

name : string

The name of the instance.

app_release_id : integer

The id of the app release the instance belongs to.

report_id : integer

The id of the report the instance belongs to.

created_at : string/time

The time the instance was created at.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

project_id : integer

The id of the project collecting all the objects that belong to this app instance.

auth_code_url : string

api_key : string

A Civis API key that can be used by this app instance.

list()

List apps

Returns:

slug : string

The slug for the application.

id : integer

The unique id of the application.

instance_name : string

A word that describes an instance of this app.

name : string

The name of the application.

list_instances(slug, *, archived='DEFAULT', app_release_id='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List the instances of a Decision Application

Parameters:

slug : string

The slug for the application.

archived : string, optional

The archival status of the requested object(s).

app_release_id : integer, optional

If supplied, return only instances matching this release.

limit : integer, optional

Number of results to return. Defaults to its maximum of 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to id. Must be one of: id, created_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The unique id of the instance.

name : string

The name of the instance.

app_release_id : integer

The id of the app release the instance belongs to.

report_id : integer

The id of the report the instance belongs to.

created_at : string/time

The time the instance was created at.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

project_id : integer

The id of the project collecting all the objects that belong to this app instance.

list_instances_projects(id, slug, *, hidden='DEFAULT')

List the projects a AppInstance belongs to

Parameters:

id : integer

The ID of the resource.

slug : string

The slug for the application.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

Returns:

id : integer

The ID for this project.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of this project.

description : string

A description of the project

users : list:

Users who can see the project
- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested object(s).

list_instances_shares(id, slug)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

slug : string

The slug for the application.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

patch_instances(id, slug, *, name='DEFAULT')

Update a given app instance

Parameters:

id : integer

The unique id of the instance.

slug : string

The slug for the application.

name : string, optional

The name of the instance.

Returns:

id : integer

The unique id of the instance.

name : string

The name of the instance.

app_release_id : integer

The id of the app release the instance belongs to.

report_id : integer

The id of the report the instance belongs to.

created_at : string/time

The time the instance was created at.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

project_id : integer

The id of the project collecting all the objects that belong to this app instance.

auth_code_url : string

api_key : string

A Civis API key that can be used by this app instance.

post_instances(slug, *, name='DEFAULT')

Create a new instance of an application of the given slug

Parameters:

slug : string

The slug for the application.

name : string, optional

The name of the instance.

Returns:

id : integer

The unique id of the instance.

name : string

The name of the instance.

app_release_id : integer

The id of the app release the instance belongs to.

report_id : integer

The id of the report the instance belongs to.

created_at : string/time

The time the instance was created at.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

project_id : integer

The id of the project collecting all the objects that belong to this app instance.

auth_code_url : string

api_key : string

A Civis API key that can be used by this app instance.

put_instances_archive(id, slug, status)

Update the archive status of this object

Parameters:

id : integer

The ID of the object.

slug : string

The slug for the application.

status : boolean

The desired archived status of the object.

Returns:

id : integer

The unique id of the instance.

name : string

The name of the instance.

app_release_id : integer

The id of the app release the instance belongs to.

report_id : integer

The id of the report the instance belongs to.

created_at : string/time

The time the instance was created at.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

project_id : integer

The id of the project collecting all the objects that belong to this app instance.

auth_code_url : string

api_key : string

A Civis API key that can be used by this app instance.

put_instances_projects(id, project_id, slug)

Add a AppInstance to a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

slug : string

The slug for the application.

Returns:

None

Response code 204: success

put_instances_shares_groups(id, slug, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

slug : string

The slug for the application.

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_instances_shares_users(id, slug, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

slug : string

The slug for the application.

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Clusters

class Clusters(session_kwargs, return_type='civis')

Methods

get_kubernetes(id) Describe a Kubernetes Cluster
get_workers(id) Describe a Worker Cluster
list_kubernetes(*[, organization_slug, ...]) List Kubernetes Clusters
list_workers(*[, limit, page_num, order, ...]) List Worker Clusters
list_workers_active_jobs(id) List Active Jobs for a Worker Cluster
list_workers_queued_jobs(id) List Queued Jobs for a Worker Cluster
get_kubernetes(id)

Describe a Kubernetes Cluster

Parameters:

id : integer

The ID of this cluster.

Returns:

id : integer

The ID of this cluster.

instance_type : string

The EC2 instance types in this cluster.

min_instances : integer

The minimum number of instances in this cluster.

max_instances : integer

The maximum number of instances in this cluster.

instance_max_memory : integer

The amount of memory available to a single instance.

instance_max_cpu : integer

The number of processor shares available to a single instance.

organization_id : string

The id of this cluster’s organization.

organization_slug : string

The slug of this cluster’s organization.

security_group_id : string

The security group to be added to the nodes of this cluster

get_workers(id)

Describe a Worker Cluster

Parameters:

id : integer

The ID of this cluster.

Returns:

id : integer

The ID of this cluster.

instance_type : string

The EC2 instance types in this cluster.

min_instances : integer

The minimum number of instances in this cluster.

max_instances : integer

The maximum number of instances in this cluster.

instances : integer

The number of instances currently in this cluster.

instance_max_memory : integer

The amount of memory available to a single instance.

instance_max_cpu : integer

The number of processor shares available to a single instance.

instance_max_disk_space : number/float

The amount of memory available to a single instance.

region : string

The AWS region that this cluster is in.

active_jobs_count : integer

The number of jobs currently being run in the cluster.

queued_jobs_count : integer

The number of jobs currently waiting to be run on the cluster.

list_kubernetes(*, organization_slug='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List Kubernetes Clusters

Parameters:

organization_slug : string, optional

The slug of this cluster’s organization.

limit : integer, optional

Number of results to return. Defaults to its maximum of 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to organization_id. Must be one of: organization_id, created_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of this cluster.

instance_type : string

The EC2 instance types in this cluster.

min_instances : integer

The minimum number of instances in this cluster.

max_instances : integer

The maximum number of instances in this cluster.

instance_max_memory : integer

The amount of memory available to a single instance.

instance_max_cpu : integer

The number of processor shares available to a single instance.

organization_id : string

The id of this cluster’s organization.

organization_slug : string

The slug of this cluster’s organization.

security_group_id : string

The security group to be added to the nodes of this cluster

list_workers(*, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List Worker Clusters

Parameters:

limit : integer, optional

Number of results to return. Defaults to its maximum of 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to id. Must be one of: id, created_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of this cluster.

instance_type : string

The EC2 instance types in this cluster.

min_instances : integer

The minimum number of instances in this cluster.

max_instances : integer

The maximum number of instances in this cluster.

region : string

The AWS region that this cluster is in.

active_jobs_count : integer

The number of jobs currently being run in the cluster.

queued_jobs_count : integer

The number of jobs currently waiting to be run on the cluster.

list_workers_active_jobs(id)

List Active Jobs for a Worker Cluster

Parameters:

id : integer

The ID of this cluster.

Returns:

id : integer

name : string

type : string

state : string

Whether the job is idle, queued, running, cancelled, or failed.

created_at : string/date-time

updated_at : string/date-time

runs : list:

Information about the most recent runs of the job.
- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

required_cpu : integer

The CPU shares required by the script.

required_disk_space : integer

The disk space in GB required by the script.

required_memory : integer

The memory in MB required by the script.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.
list_workers_queued_jobs(id)

List Queued Jobs for a Worker Cluster

Parameters:

id : integer

The ID of this cluster.

Returns:

id : integer

name : string

type : string

state : string

Whether the job is idle, queued, running, cancelled, or failed.

created_at : string/date-time

updated_at : string/date-time

runs : list:

Information about the most recent runs of the job.
- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

required_cpu : integer

The CPU shares required by the script.

required_disk_space : integer

The disk space in GB required by the script.

required_memory : integer

The memory in MB required by the script.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

Codes

class Codes(session_kwargs, return_type='civis')

Methods

delete(id) Delete a code
get(id) Show basic code info
list(*[, limit, type, featured]) List codes
patch(id, *[, name, type, body, readme, ...]) Update a code
post(name, type, body, readme, *[, score, ...]) Create a new code
put(id, name, type, body, readme, *[, ...]) Update a code
delete(id)

Delete a code

Parameters:

id : integer

The ID for this code.

Returns:

None

Response code 204: success

get(id)

Show basic code info

Parameters:

id : integer

The ID for this code.

Returns:

id : integer

The ID for this code.

name : string

Name of code.

type : string

The code’s type; e.g., Code::FrontEnd.

body : string

Actual code contents; e.g., HTML, SQL, etc.

readme : string

User specified information about this code. Markdown format accepted.

score : integer

Internal Civis Use Only.

auth_s3_url : string

Authorized_s3_link to file.

created_at : string/time

The creation time for this code.

updated_at : string/time

The last modification time for this code.

list(*, limit='DEFAULT', type='DEFAULT', featured='DEFAULT')

List codes

Parameters:

limit : integer, optional

The maximum number of codes to return.

type : string, optional

The code’s type; e.g., Code::FrontEnd.

featured : boolean, optional

If true, return featured codes.

Returns:

id : integer

The ID for this code.

name : string

Name of code.

type : string

The code’s type; e.g., Code::FrontEnd.

created_at : string/time

The creation time for this code.

updated_at : string/time

The last modification time for this code.

patch(id, *, name='DEFAULT', type='DEFAULT', body='DEFAULT', readme='DEFAULT', score='DEFAULT', auth_s3_url='DEFAULT')

Update a code

Parameters:

id : integer

The ID for this code.

name : string, optional

Name of code.

type : string, optional

The code’s type; e.g., Code::FrontEnd.

body : string, optional

Actual code contents; e.g., HTML, SQL, etc.

readme : string, optional

User specified information about this code. Markdown format accepted.

score : integer, optional

Internal Civis Use Only.

auth_s3_url : string, optional

Authorized_s3_link to file.

Returns:

None

Response code 204: success

post(name, type, body, readme, *, score='DEFAULT', auth_s3_url='DEFAULT')

Create a new code

Parameters:

name : string

Name of code.

type : string

The code’s type; e.g., Code::FrontEnd.

body : string

Actual code contents; e.g., HTML, SQL, etc.

readme : string

User specified information about this code. Markdown format accepted.

score : integer, optional

Internal Civis Use Only.

auth_s3_url : string, optional

Authorized_s3_link to file.

Returns:

None

Response code 204: success

put(id, name, type, body, readme, *, score='DEFAULT', auth_s3_url='DEFAULT')

Update a code

Parameters:

id : integer

The ID for this code.

name : string

Name of code.

type : string

The code’s type; e.g., Code::FrontEnd.

body : string

Actual code contents; e.g., HTML, SQL, etc.

readme : string

User specified information about this code. Markdown format accepted.

score : integer, optional

Internal Civis Use Only.

auth_s3_url : string, optional

Authorized_s3_link to file.

Returns:

id : integer

The ID for this code.

name : string

Name of code.

type : string

The code’s type; e.g., Code::FrontEnd.

body : string

Actual code contents; e.g., HTML, SQL, etc.

readme : string

User specified information about this code. Markdown format accepted.

score : integer

Internal Civis Use Only.

auth_s3_url : string

Authorized_s3_link to file.

created_at : string/time

The creation time for this code.

updated_at : string/time

The last modification time for this code.

Credentials

class Credentials(session_kwargs, return_type='civis')

Methods

delete_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_shares_users(id, user_id) Revoke the permissions a user has on this object
get(id) Get a credential
list(*[, type, default, limit, page_num, ...]) List credentials
list_shares(id) List users and groups permissioned on this object
post(type, username, password, *[, name, ...]) Create a credential
post_authenticate(url, remote_host_type, ...) Authenticate against a remote host
post_temporary(id, *[, duration]) Generate a temporary credential for accessing S3
put(id, type, username, password, *[, name, ...]) Update an existing credential
put_shares_groups(id, group_ids, ...[, ...]) Set the permissions groups has on this object
put_shares_users(id, user_ids, ...[, ...]) Set the permissions users have on this object
delete_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get(id)

Get a credential

Parameters:

id : integer

The ID of the credential.

Returns:

id : integer

The ID of the credential.

name : string

The name identifying the credential

type : string

The credential’s type.

username : string

The username for the credential.

description : string

A long description of the credential.

owner : string

The name of the user who this credential belongs to.

remote_host_id : integer

The ID of the remote host associated with this credential.

remote_host_name : string

The name of the remote host associated with this credential.

created_at : string/time

The creation time for this credential.

updated_at : string/time

The last modification time for this credential.

list(*, type='DEFAULT', default='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List credentials

Parameters:

type : string, optional

The type (or types) of credentials to return. One or more of: Amazon Web Services S3, BSD::API, CASS/NCOA PAF, Catalist::API, Catalist::SFTP, Certificate, Civis Platform, Custom, Database, Google, Github, JobTraits::Ftp, Salesforce User, Salesforce Client, Silverpop Application, Silverpop Refresh Token, Silverpop User, TableauUser, VAN::MyVoterFile, VAN::MyCampaign, and VAN::BothModes. Specify multiple values as a comma- separated list (e.g., “A,B”).

default : boolean, optional

If true, will return a list with a single credential which is the current user’s default credential.

limit : integer, optional

Number of results to return. Defaults to its maximum of 1000.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, created_at, name.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of the credential.

name : string

The name identifying the credential

type : string

The credential’s type.

username : string

The username for the credential.

description : string

A long description of the credential.

owner : string

The name of the user who this credential belongs to.

remote_host_id : integer

The ID of the remote host associated with this credential.

remote_host_name : string

The name of the remote host associated with this credential.

created_at : string/time

The creation time for this credential.

updated_at : string/time

The last modification time for this credential.

list_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

post(type, username, password, *, name='DEFAULT', description='DEFAULT', remote_host_id='DEFAULT', system_credential='DEFAULT')

Create a credential

Parameters:

type : string

username : string

The username for the credential.

password : string

The password for the credential.

name : string, optional

The name identifying the credential.

description : string, optional

A long description of the credential.

remote_host_id : integer, optional

The ID of the remote host associated with the credential.

system_credential : boolean, optional

Returns:

id : integer

The ID of the credential.

name : string

The name identifying the credential

type : string

The credential’s type.

username : string

The username for the credential.

description : string

A long description of the credential.

owner : string

The name of the user who this credential belongs to.

remote_host_id : integer

The ID of the remote host associated with this credential.

remote_host_name : string

The name of the remote host associated with this credential.

created_at : string/time

The creation time for this credential.

updated_at : string/time

The last modification time for this credential.

post_authenticate(url, remote_host_type, username, password)

Authenticate against a remote host

Parameters:

url : string

The URL to your host.

remote_host_type : string

The type of remote host. One of: RemoteHostTypes::BSD, RemoteHostTypes::Ftp, RemoteHostTypes::Github, RemoteHostTypes::GoogleDoc, RemoteHostTypes::JDBC, RemoteHostTypes::Redshift, RemoteHostTypes::Salesforce, and RemoteHostTypes::Van

username : string

The username for the credential.

password : string

The password for the credential.

Returns:

id : integer

The ID of the credential.

name : string

The name identifying the credential

type : string

The credential’s type.

username : string

The username for the credential.

description : string

A long description of the credential.

owner : string

The name of the user who this credential belongs to.

remote_host_id : integer

The ID of the remote host associated with this credential.

remote_host_name : string

The name of the remote host associated with this credential.

created_at : string/time

The creation time for this credential.

updated_at : string/time

The last modification time for this credential.

post_temporary(id, *, duration='DEFAULT')

Generate a temporary credential for accessing S3

Parameters:

id : integer

The ID of the credential.

duration : integer, optional

The number of seconds the temporary credential should be valid. Defaults to 15 minutes. Must not be less than 15 minutes or greater than 36 hours.

Returns:

access_key : string

The identifier of the credential.

secret_access_key : string

The secret part of the credential.

session_token : string

The session token identifier.

put(id, type, username, password, *, name='DEFAULT', description='DEFAULT', remote_host_id='DEFAULT', system_credential='DEFAULT')

Update an existing credential

Parameters:

id : integer

The ID of the credential.

type : string

username : string

The username for the credential.

password : string

The password for the credential.

name : string, optional

The name identifying the credential.

description : string, optional

A long description of the credential.

remote_host_id : integer, optional

The ID of the remote host associated with the credential.

system_credential : boolean, optional

Returns:

id : integer

The ID of the credential.

name : string

The name identifying the credential

type : string

The credential’s type.

username : string

The username for the credential.

description : string

A long description of the credential.

owner : string

The name of the user who this credential belongs to.

remote_host_id : integer

The ID of the remote host associated with this credential.

remote_host_name : string

The name of the remote host associated with this credential.

created_at : string/time

The creation time for this credential.

updated_at : string/time

The last modification time for this credential.

put_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Databases

class Databases(session_kwargs, return_type='civis')

Methods

delete_whitelist_ips(id, whitelisted_ip_id) Remove a whitelisted IP address
get_whitelist_ips(id, whitelisted_ip_id) View details about a whitelisted IP
list() List databases
list_schemas(id) List schemas in this database
list_whitelist_ips(id) List whitelisted IPs for the specified database
post_whitelist_ips(id, subnet_mask) Whitelist an IP address
delete_whitelist_ips(id, whitelisted_ip_id)

Remove a whitelisted IP address

Parameters:

id : integer

The ID of the database this rule is applied to.

whitelisted_ip_id : integer

The ID of this whitelisted IP address.

Returns:

None

Response code 204: success

get_whitelist_ips(id, whitelisted_ip_id)

View details about a whitelisted IP

Parameters:

id : integer

The ID of the database this rule is applied to.

whitelisted_ip_id : integer

The ID of this whitelisted IP address.

Returns:

id : integer

The ID of this whitelisted IP address.

remote_host_id : integer

The ID of the database this rule is applied to.

security_group_id : string

The ID of the security group this rule is applied to.

subnet_mask : string

The subnet mask that is allowed by this rule.

authorized_by : string

The user who authorized this rule.

is_active : boolean

True if the rule is applied, false if it has been revoked.

created_at : string/time

The time this rule was created.

updated_at : string/time

The time this rule was last updated.

list()

List databases

Returns:

id : integer

The ID for the database.

name : string

The name of the database.

list_schemas(id)

List schemas in this database

Parameters:

id : integer

The ID of the database.

Returns:

schema : string

The name of a schema.

list_whitelist_ips(id)

List whitelisted IPs for the specified database

Parameters:

id : integer

The ID for the database.

Returns:

id : integer

The ID of this whitelisted IP address.

remote_host_id : integer

The ID of the database this rule is applied to.

security_group_id : string

The ID of the security group this rule is applied to.

subnet_mask : string

The subnet mask that is allowed by this rule.

created_at : string/time

The time this rule was created.

updated_at : string/time

The time this rule was last updated.

post_whitelist_ips(id, subnet_mask)

Whitelist an IP address

Parameters:

id : integer

The ID of the database this rule is applied to.

subnet_mask : string

The subnet mask that is allowed by this rule.

Returns:

id : integer

The ID of this whitelisted IP address.

remote_host_id : integer

The ID of the database this rule is applied to.

security_group_id : string

The ID of the security group this rule is applied to.

subnet_mask : string

The subnet mask that is allowed by this rule.

authorized_by : string

The user who authorized this rule.

is_active : boolean

True if the rule is applied, false if it has been revoked.

created_at : string/time

The time this rule was created.

updated_at : string/time

The time this rule was last updated.

Endpoints

class Endpoints(session_kwargs, return_type='civis')

Methods

list() List API endpoints
list()

List API endpoints

Returns:

None

Response code 200: success

Enhancements

class Enhancements(session_kwargs, return_type='civis')

Methods

delete_cass_ncoa_projects(id, project_id) Remove a JobTypes::CassNcoa from a project
delete_cass_ncoa_runs(id, run_id) Cancel a run
delete_cass_ncoa_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_cass_ncoa_shares_users(id, user_id) Revoke the permissions a user has on this object
get_cass_ncoa(id) Get a CASS/NCOA Enhancement
get_cass_ncoa_runs(id, run_id) Check status of a run
list(*[, type, author, status, archived, ...]) List Enhancements
list_cass_ncoa_projects(id, *[, hidden]) List the projects a JobTypes::CassNcoa belongs to
list_cass_ncoa_runs(id, *[, limit, ...]) List runs for the given cass_ncoa
list_cass_ncoa_runs_logs(id, run_id, *[, ...]) Get the logs for a run
list_cass_ncoa_runs_outputs(id, run_id, *[, ...]) List the outputs for a run
list_cass_ncoa_shares(id) List users and groups permissioned on this object
list_types() List available enhancement types
patch_cass_ncoa(id, *[, name, schedule, ...]) Update some attributes of this CASS/NCOA Enhancement
post_cass_ncoa(name, source, *[, schedule, ...]) Create a CASS/NCOA Enhancement
post_cass_ncoa_cancel(id) Cancel a run
post_cass_ncoa_runs(id) Start a run
put_cass_ncoa(id, name, source, *[, ...]) Replace all attributes of this CASS/NCOA Enhancement
put_cass_ncoa_archive(id, status) Update the archive status of this object
put_cass_ncoa_projects(id, project_id) Add a JobTypes::CassNcoa to a project
put_cass_ncoa_shares_groups(id, group_ids, ...) Set the permissions groups has on this object
put_cass_ncoa_shares_users(id, user_ids, ...) Set the permissions users have on this object
delete_cass_ncoa_projects(id, project_id)

Remove a JobTypes::CassNcoa from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

delete_cass_ncoa_runs(id, run_id)

Cancel a run

Parameters:

id : integer

The ID of the cass_ncoa.

run_id : integer

The ID of the run.

Returns:

None

Response code 202: success

delete_cass_ncoa_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_cass_ncoa_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get_cass_ncoa(id)

Get a CASS/NCOA Enhancement

Parameters:

id : integer

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

type : string

The type of the enhancement (e.g CASS-NCOA)

created_at : string/time

The time this enhancement was created.

updated_at : string/time

The time the enhancement was last updated.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

state : string

The status of the enhancement’s last run

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

Parent ID that triggers this enhancement.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

destination : dict:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string

The limiting sql.

archived : string

The archival status of the requested object(s).

get_cass_ncoa_runs(id, run_id)

Check status of a run

Parameters:

id : integer

The ID of the cass_ncoa.

run_id : integer

The ID of the run.

Returns:

id : integer

The ID of the run.

cass_ncoa_id : integer

The ID of the cass_ncoa.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

list(*, type='DEFAULT', author='DEFAULT', status='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List Enhancements

Parameters:

type : string, optional

If specified, return objects of these types.

author : string, optional

If specified, return objects from this author. Must use user IDs. A comma separated list of IDs is also accepted to return objects from multiple authors.

status : string, optional

If specified, returns objects with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.

archived : string, optional

The archival status of the requested object(s).

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at, last_run.updated_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

type : string

The type of the enhancement (e.g CASS-NCOA)

created_at : string/time

The time this enhancement was created.

updated_at : string/time

The time the enhancement was last updated.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

state : string

The status of the enhancement’s last run

archived : string

The archival status of the requested object(s).

list_cass_ncoa_projects(id, *, hidden='DEFAULT')

List the projects a JobTypes::CassNcoa belongs to

Parameters:

id : integer

The ID of the resource.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

Returns:

id : integer

The ID for this project.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of this project.

description : string

A description of the project

users : list:

Users who can see the project
- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested object(s).

list_cass_ncoa_runs(id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List runs for the given cass_ncoa

Parameters:

id : integer

The ID of the cass_ncoa.

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 100.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to id. Must be one of: id.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of the run.

cass_ncoa_id : integer

The ID of the cass_ncoa.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

list_cass_ncoa_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')

Get the logs for a run

Parameters:

id : integer

The ID of the cass_ncoa.

run_id : integer

The ID of the run.

last_id : integer, optional

The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.

limit : integer, optional

The maximum number of log messages to return. Default of 10000.

Returns:

id : integer

The ID of the log.

created_at : string/date-time

The time the log was created.

message : string

The log message.

level : string

The level of the log. One of unknown,fatal,error,warn,info,debug.

list_cass_ncoa_runs_outputs(id, run_id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List the outputs for a run

Parameters:

id : integer

The ID of the job.

run_id : integer

The ID of the run.

limit : integer, optional

Number of results to return. Defaults to its maximum of 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to created_at. Must be one of: created_at, id.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

object_type : string

The type of the output. Valid values are File, Table, Report, Project, or Credential

object_id : integer

The ID of the output object.

name : string

The name of the output object.

link : string

The link to retrieve the output object.

list_cass_ncoa_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_types()

List available enhancement types

Returns:

name : string

The name of the type.

patch_cass_ncoa(id, *, name='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', source='DEFAULT', destination='DEFAULT', column_mapping='DEFAULT', use_default_column_mapping='DEFAULT', perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT', limiting_sql='DEFAULT')

Update some attributes of this CASS/NCOA Enhancement

Parameters:

id : integer

The ID for the enhancement.

name : string, optional

The name of the enhancement.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer, optional

Parent ID that triggers this enhancement.

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

source : dict, optional:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

destination : dict, optional:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict, optional:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean, optional

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean, optional

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer, optional

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string, optional

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string, optional

The limiting sql.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

type : string

The type of the enhancement (e.g CASS-NCOA)

created_at : string/time

The time this enhancement was created.

updated_at : string/time

The time the enhancement was last updated.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

state : string

The status of the enhancement’s last run

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

Parent ID that triggers this enhancement.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

destination : dict:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string

The limiting sql.

archived : string

The archival status of the requested object(s).

post_cass_ncoa(name, source, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', destination='DEFAULT', column_mapping='DEFAULT', use_default_column_mapping='DEFAULT', perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT', limiting_sql='DEFAULT')

Create a CASS/NCOA Enhancement

Parameters:

name : string

The name of the enhancement.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer, optional

Parent ID that triggers this enhancement.

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

destination : dict, optional:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict, optional:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean, optional

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean, optional

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer, optional

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string, optional

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string, optional

The limiting sql.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

type : string

The type of the enhancement (e.g CASS-NCOA)

created_at : string/time

The time this enhancement was created.

updated_at : string/time

The time the enhancement was last updated.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

state : string

The status of the enhancement’s last run

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

Parent ID that triggers this enhancement.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

destination : dict:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string

The limiting sql.

archived : string

The archival status of the requested object(s).

post_cass_ncoa_cancel(id)

Cancel a run

Parameters:

id : integer

The ID of the job.

Returns:

id : integer

The ID of the run.

state : string

The state of the run, one of ‘queued’, ‘running’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

post_cass_ncoa_runs(id)

Start a run

Parameters:

id : integer

The ID of the cass_ncoa.

Returns:

id : integer

The ID of the run.

cass_ncoa_id : integer

The ID of the cass_ncoa.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

put_cass_ncoa(id, name, source, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', destination='DEFAULT', column_mapping='DEFAULT', use_default_column_mapping='DEFAULT', perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT', limiting_sql='DEFAULT')

Replace all attributes of this CASS/NCOA Enhancement

Parameters:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer, optional

Parent ID that triggers this enhancement.

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

destination : dict, optional:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict, optional:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean, optional

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean, optional

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer, optional

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string, optional

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string, optional

The limiting sql.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

type : string

The type of the enhancement (e.g CASS-NCOA)

created_at : string/time

The time this enhancement was created.

updated_at : string/time

The time the enhancement was last updated.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

state : string

The status of the enhancement’s last run

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

Parent ID that triggers this enhancement.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

destination : dict:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string

The limiting sql.

archived : string

The archival status of the requested object(s).

put_cass_ncoa_archive(id, status)

Update the archive status of this object

Parameters:

id : integer

The ID of the object.

status : boolean

The desired archived status of the object.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement.

type : string

The type of the enhancement (e.g CASS-NCOA)

created_at : string/time

The time this enhancement was created.

updated_at : string/time

The time the enhancement was last updated.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

state : string

The status of the enhancement’s last run

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

Parent ID that triggers this enhancement.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

source : dict:

- database_table : dict::
    - schema : string
        The schema name of the source table.
    - table : string
        The name of the source table.
    - remote_host_id : integer
        The ID of the database host for the table.
    - credential_id : integer
        The id of the credentials to be used when performing the
        enhancement.
    - multipart_key : list
        The source table primary key.

destination : dict:

- database_table : dict::
    - schema : string
        The schema name for the output data.
    - table : string
        The table name for the output data.

column_mapping : dict:

- address1 : string
    The first address line.
- address2 : string
    The second address line.
- city : string
    The city of an address.
- state : string
    The state of an address.
- zip : string
    The zip code of an address.
- name : string
    The full name of the resident at this address. If needed, separate
    multiple columns with `+`, e.g. `first_name+last_name`
- company : string
    The name of the company located at this address.

use_default_column_mapping : boolean

Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.

perform_ncoa : boolean

Whether to update addresses for records matching the National Change of Address (NCOA) database.

ncoa_credential_id : integer

Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.

output_level : string

The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.

limiting_sql : string

The limiting sql.

archived : string

The archival status of the requested object(s).

put_cass_ncoa_projects(id, project_id)

Add a JobTypes::CassNcoa to a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

put_cass_ncoa_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_cass_ncoa_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Exports

class Exports(session_kwargs, return_type='civis')

Methods

list(*[, type, author, status, hidden, ...]) List
list(*, type='DEFAULT', author='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List

Parameters:

type : string, optional

If specified, return exports of these types. It accepts a comma-separated list, possible values are ‘database’ and ‘gdoc’.

author : string, optional

If specified, return exports from this author. It accepts a comma-separated list of author ids.

status : string, optional

If specified, returns export with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

archived : string, optional

The archival status of the requested object(s).

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at, last_run.updated_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for this export.

name : string

The name of this export.

type : string

The type of export.

created_at : string/time

The creation time for this export.

updated_at : string/time

The last modification time for this export.

state : string

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

Files

class Files(session_kwargs, return_type='civis')

Methods

delete_projects(id, project_id) Remove a Data::S3File from a project
delete_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_shares_users(id, user_id) Revoke the permissions a user has on this object
get(id, *[, link_expires_at]) Get details about a file
list_projects(id, *[, hidden]) List the projects a Data::S3File belongs to
list_shares(id) List users and groups permissioned on this object
post(name, *[, expires_at]) Initiate an upload of a file into the platform
post_multipart(name, num_parts, *[, expires_at]) Initiate a multipart upload
post_multipart_complete(id) Complete a multipart upload
put_projects(id, project_id) Add a Data::S3File to a project
put_shares_groups(id, group_ids, ...[, ...]) Set the permissions groups has on this object
put_shares_users(id, user_ids, ...[, ...]) Set the permissions users have on this object
delete_projects(id, project_id)

Remove a Data::S3File from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

delete_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get(id, *, link_expires_at='DEFAULT')

Get details about a file

Parameters:

id : integer

The ID of the file object.

link_expires_at : string, optional

The date and time the download link will expire. Must be a time between now and 36 hours from now. Defaults to 30 minutes from now.

Returns:

id : integer

The ID of the file object.

name : string

The file name.

created_at : string/date-time

The date and time the file was created.

file_size : integer

The file size.

expires_at : string/date-time

The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.

download_url : string

A JSON string containing information about the URL of the file.

file_url : string

The URL that may be used to download the file.

list_projects(id, *, hidden='DEFAULT')

List the projects a Data::S3File belongs to

Parameters:

id : integer

The ID of the resource.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

Returns:

id : integer

The ID for this project.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of this project.

description : string

A description of the project

users : list:

Users who can see the project
- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested object(s).

list_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

post(name, *, expires_at='DEFAULT')

Initiate an upload of a file into the platform

Parameters:

name : string

The file name.

expires_at : string/date-time, optional

The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.

Returns:

id : integer

The ID of the file object.

name : string

The file name.

created_at : string/date-time

The date and time the file was created.

file_size : integer

The file size.

expires_at : string/date-time

The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.

upload_url : string

The URL that may be used to upload a file. To use the upload URL, initiate a POST request to the given URL with the file you wish to import as the “file” form field.

upload_fields : dict

A hash containing the form fields to be included with the POST request.

post_multipart(name, num_parts, *, expires_at='DEFAULT')

Initiate a multipart upload

Parameters:

name : string

The file name.

num_parts : integer

The number of parts in which the file will be uploaded. This parameter determines the number of presigned URLs that are returned.

expires_at : string/date-time, optional

The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.

Returns:

id : integer

The ID of the file object.

name : string

The file name.

created_at : string/date-time

The date and time the file was created.

file_size : integer

The file size.

expires_at : string/date-time

The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.

upload_urls : list

An array of URLs that may be used to upload file parts. Use separate PUT requests to complete the part uploads. Links expire after 12 hours.

post_multipart_complete(id)

Complete a multipart upload

Parameters:

id : integer

The ID of the file object.

Returns:

None

Response code 204: success

put_projects(id, project_id)

Add a Data::S3File to a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

put_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Groups

class Groups(session_kwargs, return_type='civis')

Methods

list(*[, query, permission, limit, ...]) List Groups
list(*, query='DEFAULT', permission='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List Groups

Parameters:

query : string, optional

If specified, it will filter the groups returned. Prefix matching is supported (e.g., “query=group” will return “group” and “group of people”, but not “my group”.

permission : string, optional

A permissions string, one of “read”, “write”, or “manage”. Lists only groups for which the current user has that permission.

limit : integer, optional

Number of results to return. Defaults to 50. Maximum allowed is 1000.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to name. Must be one of: name, created_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of this group.

name : string

This group’s name.

created_at : string/time

The date and time when this group was created.

slug : string

The slug for this group.

organization_id : integer

The organization associated with this group.

Imports

class Imports(session_kwargs, return_type='civis')

Methods

delete_files_runs(id, run_id) Cancel a run
delete_projects(id, project_id) Remove a JobTypes::Import from a project
delete_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_shares_users(id, user_id) Revoke the permissions a user has on this object
get(id) Get details about an import
get_batches(id) Get details about a batch import
get_files_runs(id, run_id) Check status of a run
list(*[, type, author, destination, status, ...]) List
list_batches(*[, hidden, limit, page_num, ...]) List batch imports
list_files_runs(id, *[, limit, page_num, ...]) List runs for the given import
list_files_runs_logs(id, run_id, *[, ...]) Get the logs for a run
list_projects(id, *[, hidden]) List the projects a JobTypes::Import belongs to
list_runs(id) Get the run history of this import
list_runs_logs(id, run_id, *[, last_id, limit]) Get the logs for a run
list_shares(id) List users and groups permissioned on this object
post(name, sync_type, is_outbound, *[, ...]) Create a new import configuration
post_batches(file_ids, schema, table, ...[, ...]) Upload multiple files to Redshift
post_cancel(id) Cancel a run
post_files(schema, name, remote_host_id, ...) Initate an import of a tabular file into the platform
post_files_runs(id) Start a run
post_runs(id) Run an import
post_syncs(id, source, destination, *[, ...]) Create a sync
put(id, name, sync_type, is_outbound, *[, ...]) Update an import
put_archive(id, status) Update the archive status of this object
put_projects(id, project_id) Add a JobTypes::Import to a project
put_shares_groups(id, group_ids, ...[, ...]) Set the permissions groups has on this object
put_shares_users(id, user_ids, ...[, ...]) Set the permissions users have on this object
put_syncs(id, sync_id, source, destination, *) Update a sync
put_syncs_archive(id, sync_id, *[, status]) Update the archive status of this sync
delete_files_runs(id, run_id)

Cancel a run

Parameters:

id : integer

The ID of the import.

run_id : integer

The ID of the run.

Returns:

None

Response code 202: success

delete_projects(id, project_id)

Remove a JobTypes::Import from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

delete_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get(id)

Get details about an import

Parameters:

id : integer

The ID for the import.

Returns:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

source : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

destination : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

parent_id : integer

Parent id to trigger this import from

id : integer

The ID for the import.

is_outbound : boolean

job_type : string

The job type of this import.

syncs : list:

List of syncs.
- id : integer
- source : dict::
    - id : integer
        The ID of the table or file, if available.
    - path : string
        The path of the dataset to sync from; for a database source,
        schema.tablename. If you are doing a Google Sheet export, this can
        be blank. This is a legacy parameter, it is recommended you use one
        of the following: databaseTable, file, googleWorksheet, salesforce,
        silverpop
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - file : dict::
        - id : integer
            The file id.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
    - salesforce : dict::
        - object_name : string
            The Salesforce object name.
    - silverpop : dict::
        - list_id : integer
            The Silverpop list id.
- destination : dict::
    - path : string
        The schema.tablename to sync to. If you are doing a Google Sheet
        export, this is the spreadsheet and sheet name separated by a
        period. i.e. if you have a spreadsheet named "MySpreadsheet" and a
        sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1".
        This is a legacy parameter, it is recommended you use one of the
        following: databaseTable, googleWorksheet
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
- advanced_options : dict::
    - max_errors : integer
    - existing_table_rows : string
    - distkey : string
    - sortkey1 : string
    - sortkey2 : string
    - column_delimiter : string
    - column_overrides : dict
        Hash used for overriding auto-detected names and types, with keys
        being the current name of the column being overridden.
    - identity_column : string
    - row_chunk_size : integer
    - wipe_destination_table : boolean
    - truncate_long_lines : boolean
    - invalid_char_replacement : string
    - verify_table_row_counts : boolean
    - partition_column_name : string
    - partition_schema_name : string
    - partition_table_name : string
    - partition_table_partition_column_min_name : string
    - partition_table_partition_column_max_name : string
    - last_modified_column : string
    - mysql_catalog_matches_schema : boolean
    - chunking_method : string
        The method used to break the data into smaller chunks for transfer.
        The value can be set to sorted_by_identity_columns or if not set
        the chunking method will be choosen automatically.
    - first_row_is_header : boolean
    - export_action : string
        The kind of export action you want to have the export execute. Set
        to "newsprsht" if you want a new worksheet inside a new
        spreadsheet. Set to "newwksht" if you want a new worksheet inside
        an existing spreadsheet. Set to "updatewksht" if you want to
        overwrite an existing worksheet inside an existing spreadsheet. Set
        to "appendwksht" if you want to append to the end of an existing
        worksheet inside an existing spreadsheet.
    - sql_query : string
        If you are doing a Google Sheet export, this is your SQL query.
    - contact_lists : string
    - soql_query : string

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this import.

hidden : boolean

The hidden status of the object.

archived : string

The archival status of the requested object(s).

get_batches(id)

Get details about a batch import

Parameters:

id : integer

The ID for the import.

Returns:

id : integer

The ID for the import.

schema : string

The destination schema name. This schema must already exist in Redshift.

table : string

The destination table name, without the schema prefix. This table must already exist in Redshift.

remote_host_id : integer

The ID of the destination database host.

state : string

The state of the run; one of “queued”, “running”, “succeeded”, “failed”, or “cancelled”.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error returned by the run, if any.

hidden : boolean

The hidden status of the object.

get_files_runs(id, run_id)

Check status of a run

Parameters:

id : integer

The ID of the import.

run_id : integer

The ID of the run.

Returns:

id : integer

The ID of the run.

import_id : integer

The ID of the import.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

list(*, type='DEFAULT', author='DEFAULT', destination='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List

Parameters:

type : string, optional

If specified, return imports of these types. It accepts a comma-separated list, possible values are ‘AutoImport’, ‘DbSync’, ‘Salesforce’, ‘GdocImport’.

author : string, optional

If specified, return imports from this author. It accepts a comma-separated list of author ids.

destination : string, optional

If specified, returns imports with one of these destinations. It accepts a comma-separated list of remote host ids.

status : string, optional

If specified, returns imports with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

archived : string, optional

The archival status of the requested object(s).

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at, last_run.updated_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

source : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

destination : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

id : integer

The ID for the import.

is_outbound : boolean

job_type : string

The job type of this import.

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

time_zone : string

The time zone of this import.

archived : string

The archival status of the requested object(s).

list_batches(*, hidden='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List batch imports

Parameters:

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, created_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for the import.

schema : string

The destination schema name. This schema must already exist in Redshift.

table : string

The destination table name, without the schema prefix. This table must already exist in Redshift.

remote_host_id : integer

The ID of the destination database host.

state : string

The state of the run; one of “queued”, “running”, “succeeded”, “failed”, or “cancelled”.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error returned by the run, if any.

list_files_runs(id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List runs for the given import

Parameters:

id : integer

The ID of the import.

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 100.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to id. Must be one of: id.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of the run.

import_id : integer

The ID of the import.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

list_files_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')

Get the logs for a run

Parameters:

id : integer

The ID of the import.

run_id : integer

The ID of the run.

last_id : integer, optional

The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.

limit : integer, optional

The maximum number of log messages to return. Default of 10000.

Returns:

id : integer

The ID of the log.

created_at : string/date-time

The time the log was created.

message : string

The log message.

level : string

The level of the log. One of unknown,fatal,error,warn,info,debug.

list_projects(id, *, hidden='DEFAULT')

List the projects a JobTypes::Import belongs to

Parameters:

id : integer

The ID of the resource.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

Returns:

id : integer

The ID for this project.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of this project.

description : string

A description of the project

users : list:

Users who can see the project
- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested object(s).

list_runs(id)

Get the run history of this import

Parameters:

id : integer

Returns:

id : integer

state : string

created_at : string/time

The time that the run was queued.

started_at : string/time

The time that the run started.

finished_at : string/time

The time that the run completed.

error : string

The error message for this run, if present.

list_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')

Get the logs for a run

Parameters:

id : integer

The ID of the import.

run_id : integer

The ID of the run.

last_id : integer, optional

The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.

limit : integer, optional

The maximum number of log messages to return. Default of 10000.

Returns:

id : integer

The ID of the log.

created_at : string/date-time

The time the log was created.

message : string

The log message.

level : string

The level of the log. One of unknown,fatal,error,warn,info,debug.

list_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

post(name, sync_type, is_outbound, *, source='DEFAULT', destination='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', parent_id='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT')

Create a new import configuration

Parameters:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

is_outbound : boolean

source : dict, optional:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.

destination : dict, optional:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

parent_id : integer, optional

Parent id to trigger this import from

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this import.

hidden : boolean, optional

The hidden status of the object.

Returns:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

source : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

destination : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

parent_id : integer

Parent id to trigger this import from

id : integer

The ID for the import.

is_outbound : boolean

job_type : string

The job type of this import.

syncs : list:

List of syncs.
- id : integer
- source : dict::
    - id : integer
        The ID of the table or file, if available.
    - path : string
        The path of the dataset to sync from; for a database source,
        schema.tablename. If you are doing a Google Sheet export, this can
        be blank. This is a legacy parameter, it is recommended you use one
        of the following: databaseTable, file, googleWorksheet, salesforce,
        silverpop
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - file : dict::
        - id : integer
            The file id.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
    - salesforce : dict::
        - object_name : string
            The Salesforce object name.
    - silverpop : dict::
        - list_id : integer
            The Silverpop list id.
- destination : dict::
    - path : string
        The schema.tablename to sync to. If you are doing a Google Sheet
        export, this is the spreadsheet and sheet name separated by a
        period. i.e. if you have a spreadsheet named "MySpreadsheet" and a
        sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1".
        This is a legacy parameter, it is recommended you use one of the
        following: databaseTable, googleWorksheet
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
- advanced_options : dict::
    - max_errors : integer
    - existing_table_rows : string
    - distkey : string
    - sortkey1 : string
    - sortkey2 : string
    - column_delimiter : string
    - column_overrides : dict
        Hash used for overriding auto-detected names and types, with keys
        being the current name of the column being overridden.
    - identity_column : string
    - row_chunk_size : integer
    - wipe_destination_table : boolean
    - truncate_long_lines : boolean
    - invalid_char_replacement : string
    - verify_table_row_counts : boolean
    - partition_column_name : string
    - partition_schema_name : string
    - partition_table_name : string
    - partition_table_partition_column_min_name : string
    - partition_table_partition_column_max_name : string
    - last_modified_column : string
    - mysql_catalog_matches_schema : boolean
    - chunking_method : string
        The method used to break the data into smaller chunks for transfer.
        The value can be set to sorted_by_identity_columns or if not set
        the chunking method will be choosen automatically.
    - first_row_is_header : boolean
    - export_action : string
        The kind of export action you want to have the export execute. Set
        to "newsprsht" if you want a new worksheet inside a new
        spreadsheet. Set to "newwksht" if you want a new worksheet inside
        an existing spreadsheet. Set to "updatewksht" if you want to
        overwrite an existing worksheet inside an existing spreadsheet. Set
        to "appendwksht" if you want to append to the end of an existing
        worksheet inside an existing spreadsheet.
    - sql_query : string
        If you are doing a Google Sheet export, this is your SQL query.
    - contact_lists : string
    - soql_query : string

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this import.

hidden : boolean

The hidden status of the object.

archived : string

The archival status of the requested object(s).

post_batches(file_ids, schema, table, remote_host_id, credential_id, *, column_delimiter='DEFAULT', first_row_is_header='DEFAULT', compression='DEFAULT', hidden='DEFAULT')

Upload multiple files to Redshift

Parameters:

file_ids : list

The file IDs for the import.

schema : string

The destination schema name. This schema must already exist in Redshift.

table : string

The destination table name, without the schema prefix. This table must already exist in Redshift.

remote_host_id : integer

The ID of the destination database host.

credential_id : integer

The ID of the credentials to be used when performing the database import.

column_delimiter : string, optional

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. If unspecified, defaults to “comma”.

first_row_is_header : boolean, optional

A boolean value indicating whether or not the first row is a header row. If unspecified, defaults to false.

compression : string, optional

The type of compression. Valid arguments are “gzip”, “zip”, and “none”. If unspecified, defaults to “gzip”.

hidden : boolean, optional

The hidden status of the object.

Returns:

id : integer

The ID for the import.

schema : string

The destination schema name. This schema must already exist in Redshift.

table : string

The destination table name, without the schema prefix. This table must already exist in Redshift.

remote_host_id : integer

The ID of the destination database host.

state : string

The state of the run; one of “queued”, “running”, “succeeded”, “failed”, or “cancelled”.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error returned by the run, if any.

hidden : boolean

The hidden status of the object.

post_cancel(id)

Cancel a run

Parameters:

id : integer

The ID of the job.

Returns:

id : integer

The ID of the run.

state : string

The state of the run, one of ‘queued’, ‘running’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

post_files(schema, name, remote_host_id, credential_id, *, max_errors='DEFAULT', existing_table_rows='DEFAULT', distkey='DEFAULT', sortkey1='DEFAULT', sortkey2='DEFAULT', column_delimiter='DEFAULT', first_row_is_header='DEFAULT', multipart='DEFAULT', hidden='DEFAULT')

Initate an import of a tabular file into the platform

Parameters:

schema : string

The schema of the destination table.

name : string

The name of the destination table.

remote_host_id : integer

The id of the destination database host.

credential_id : integer

The id of the credentials to be used when performing the database import.

max_errors : integer, optional

The maximum number of rows with errors to remove from the import before failing.

existing_table_rows : string, optional

The behaviour if a table with the requested name already exists. One of “fail”, “truncate”, “append”, or “drop”.Defaults to “fail”.

distkey : string, optional

The column to use as the distkey for the table.

sortkey1 : string, optional

The column to use as the sort key for the table.

sortkey2 : string, optional

The second column in a compound sortkey for the table.

column_delimiter : string, optional

The column delimiter of the file. If column_delimiter is null or omitted, it will be auto-detected. Valid arguments are “comma”, “tab”, and “pipe”.

first_row_is_header : boolean, optional

A boolean value indicating whether or not the first row is a header row. If first_row_is_header is null or omitted, it will be auto-detected.

multipart : boolean, optional

If true, the upload URI will require a multipart/form-data POST request. Defaults to false.

hidden : boolean, optional

The hidden status of the object.

Returns:

id : integer

The id of the import.

upload_uri : string

The URI which may be used to upload a tabular file for import. You must use this URI to upload the file you wish imported and then inform the Civis API when your upload is complete using the URI given by the runUri field of this reponse.

run_uri : string

The URI to POST to once the file upload is complete. After uploading the file using the URI given in the uploadUri attribute of the reponse, POST to this URI to initiate the import of your uploaded file into the platform.

upload_fields : dict

If multipart was set to true, these fields should be included in the multipart upload.

post_files_runs(id)

Start a run

Parameters:

id : integer

The ID of the import.

Returns:

id : integer

The ID of the run.

import_id : integer

The ID of the import.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

post_runs(id)

Run an import

Parameters:

id : integer

The ID of the import to run.

Returns:

run_id : integer

The ID of the new run triggered.

post_syncs(id, source, destination, *, advanced_options='DEFAULT')

Create a sync

Parameters:

id : integer

source : dict:

- path : string
    The path of the dataset to sync from; for a database source,
    schema.tablename. If you are doing a Google Sheet export, this can be
    blank. This is a legacy parameter, it is recommended you use one of the
    following: databaseTable, file, googleWorksheet, salesforce, silverpop
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- file : dict
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.
- silverpop : dict::
    - list_id : integer
        The Silverpop list id.

destination : dict:

- path : string
    The schema.tablename to sync to. If you are doing a Google Sheet
    export, this is the spreadsheet and sheet name separated by a period.
    i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called
    "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy
    parameter, it is recommended you use one of the following:
    databaseTable, googleWorksheet
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.

advanced_options : dict, optional:

- max_errors : integer
- existing_table_rows : string
- distkey : string
- sortkey1 : string
- sortkey2 : string
- column_delimiter : string
- column_overrides : dict
    Hash used for overriding auto-detected names and types, with keys being
    the current name of the column being overridden.
- identity_column : string
- row_chunk_size : integer
- wipe_destination_table : boolean
- truncate_long_lines : boolean
- invalid_char_replacement : string
- verify_table_row_counts : boolean
- partition_column_name : string
- partition_schema_name : string
- partition_table_name : string
- partition_table_partition_column_min_name : string
- partition_table_partition_column_max_name : string
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
- chunking_method : string
    The method used to break the data into smaller chunks for transfer.
    The value can be set to sorted_by_identity_columns or if not set the
    chunking method will be choosen automatically.
- first_row_is_header : boolean
- export_action : string
    The kind of export action you want to have the export execute. Set to
    "newsprsht" if you want a new worksheet inside a new spreadsheet. Set
    to "newwksht" if you want a new worksheet inside an existing
    spreadsheet. Set to "updatewksht" if you want to overwrite an existing
    worksheet inside an existing spreadsheet. Set to "appendwksht" if you
    want to append to the end of an existing worksheet inside an existing
    spreadsheet.
- sql_query : string
    If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
Returns:

id : integer

source : dict:

- id : integer
    The ID of the table or file, if available.
- path : string
    The path of the dataset to sync from; for a database source,
    schema.tablename. If you are doing a Google Sheet export, this can be
    blank. This is a legacy parameter, it is recommended you use one of the
    following: databaseTable, file, googleWorksheet, salesforce, silverpop
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.
- silverpop : dict::
    - list_id : integer
        The Silverpop list id.

destination : dict:

- path : string
    The schema.tablename to sync to. If you are doing a Google Sheet
    export, this is the spreadsheet and sheet name separated by a period.
    i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called
    "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy
    parameter, it is recommended you use one of the following:
    databaseTable, googleWorksheet
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.

advanced_options : dict:

- max_errors : integer
- existing_table_rows : string
- distkey : string
- sortkey1 : string
- sortkey2 : string
- column_delimiter : string
- column_overrides : dict
    Hash used for overriding auto-detected names and types, with keys being
    the current name of the column being overridden.
- identity_column : string
- row_chunk_size : integer
- wipe_destination_table : boolean
- truncate_long_lines : boolean
- invalid_char_replacement : string
- verify_table_row_counts : boolean
- partition_column_name : string
- partition_schema_name : string
- partition_table_name : string
- partition_table_partition_column_min_name : string
- partition_table_partition_column_max_name : string
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
- chunking_method : string
    The method used to break the data into smaller chunks for transfer.
    The value can be set to sorted_by_identity_columns or if not set the
    chunking method will be choosen automatically.
- first_row_is_header : boolean
- export_action : string
    The kind of export action you want to have the export execute. Set to
    "newsprsht" if you want a new worksheet inside a new spreadsheet. Set
    to "newwksht" if you want a new worksheet inside an existing
    spreadsheet. Set to "updatewksht" if you want to overwrite an existing
    worksheet inside an existing spreadsheet. Set to "appendwksht" if you
    want to append to the end of an existing worksheet inside an existing
    spreadsheet.
- sql_query : string
    If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
put(id, name, sync_type, is_outbound, *, source='DEFAULT', destination='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', parent_id='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT')

Update an import

Parameters:

id : integer

The ID for the import.

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

is_outbound : boolean

source : dict, optional:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.

destination : dict, optional:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

parent_id : integer, optional

Parent id to trigger this import from

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this import.

Returns:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

source : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

destination : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

parent_id : integer

Parent id to trigger this import from

id : integer

The ID for the import.

is_outbound : boolean

job_type : string

The job type of this import.

syncs : list:

List of syncs.
- id : integer
- source : dict::
    - id : integer
        The ID of the table or file, if available.
    - path : string
        The path of the dataset to sync from; for a database source,
        schema.tablename. If you are doing a Google Sheet export, this can
        be blank. This is a legacy parameter, it is recommended you use one
        of the following: databaseTable, file, googleWorksheet, salesforce,
        silverpop
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - file : dict::
        - id : integer
            The file id.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
    - salesforce : dict::
        - object_name : string
            The Salesforce object name.
    - silverpop : dict::
        - list_id : integer
            The Silverpop list id.
- destination : dict::
    - path : string
        The schema.tablename to sync to. If you are doing a Google Sheet
        export, this is the spreadsheet and sheet name separated by a
        period. i.e. if you have a spreadsheet named "MySpreadsheet" and a
        sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1".
        This is a legacy parameter, it is recommended you use one of the
        following: databaseTable, googleWorksheet
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
- advanced_options : dict::
    - max_errors : integer
    - existing_table_rows : string
    - distkey : string
    - sortkey1 : string
    - sortkey2 : string
    - column_delimiter : string
    - column_overrides : dict
        Hash used for overriding auto-detected names and types, with keys
        being the current name of the column being overridden.
    - identity_column : string
    - row_chunk_size : integer
    - wipe_destination_table : boolean
    - truncate_long_lines : boolean
    - invalid_char_replacement : string
    - verify_table_row_counts : boolean
    - partition_column_name : string
    - partition_schema_name : string
    - partition_table_name : string
    - partition_table_partition_column_min_name : string
    - partition_table_partition_column_max_name : string
    - last_modified_column : string
    - mysql_catalog_matches_schema : boolean
    - chunking_method : string
        The method used to break the data into smaller chunks for transfer.
        The value can be set to sorted_by_identity_columns or if not set
        the chunking method will be choosen automatically.
    - first_row_is_header : boolean
    - export_action : string
        The kind of export action you want to have the export execute. Set
        to "newsprsht" if you want a new worksheet inside a new
        spreadsheet. Set to "newwksht" if you want a new worksheet inside
        an existing spreadsheet. Set to "updatewksht" if you want to
        overwrite an existing worksheet inside an existing spreadsheet. Set
        to "appendwksht" if you want to append to the end of an existing
        worksheet inside an existing spreadsheet.
    - sql_query : string
        If you are doing a Google Sheet export, this is your SQL query.
    - contact_lists : string
    - soql_query : string

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this import.

hidden : boolean

The hidden status of the object.

archived : string

The archival status of the requested object(s).

put_archive(id, status)

Update the archive status of this object

Parameters:

id : integer

The ID of the object.

status : boolean

The desired archived status of the object.

Returns:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.

source : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

destination : dict:

- remote_host_id : integer
- credential_id : integer
- additional_credentials : list
    Array that holds additional credentials used for specific imports. For
    salesforce imports, the first and only element is the client credential
    id.
- name : string

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

parent_id : integer

Parent id to trigger this import from

id : integer

The ID for the import.

is_outbound : boolean

job_type : string

The job type of this import.

syncs : list:

List of syncs.
- id : integer
- source : dict::
    - id : integer
        The ID of the table or file, if available.
    - path : string
        The path of the dataset to sync from; for a database source,
        schema.tablename. If you are doing a Google Sheet export, this can
        be blank. This is a legacy parameter, it is recommended you use one
        of the following: databaseTable, file, googleWorksheet, salesforce,
        silverpop
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - file : dict::
        - id : integer
            The file id.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
    - salesforce : dict::
        - object_name : string
            The Salesforce object name.
    - silverpop : dict::
        - list_id : integer
            The Silverpop list id.
- destination : dict::
    - path : string
        The schema.tablename to sync to. If you are doing a Google Sheet
        export, this is the spreadsheet and sheet name separated by a
        period. i.e. if you have a spreadsheet named "MySpreadsheet" and a
        sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1".
        This is a legacy parameter, it is recommended you use one of the
        following: databaseTable, googleWorksheet
    - database_table : dict::
        - schema : string
            The database schema name.
        - table : string
            The database table name.
    - google_worksheet : dict::
        - spreadsheet : string
            The spreadsheet document name.
        - worksheet : string
            The worksheet tab name.
- advanced_options : dict::
    - max_errors : integer
    - existing_table_rows : string
    - distkey : string
    - sortkey1 : string
    - sortkey2 : string
    - column_delimiter : string
    - column_overrides : dict
        Hash used for overriding auto-detected names and types, with keys
        being the current name of the column being overridden.
    - identity_column : string
    - row_chunk_size : integer
    - wipe_destination_table : boolean
    - truncate_long_lines : boolean
    - invalid_char_replacement : string
    - verify_table_row_counts : boolean
    - partition_column_name : string
    - partition_schema_name : string
    - partition_table_name : string
    - partition_table_partition_column_min_name : string
    - partition_table_partition_column_max_name : string
    - last_modified_column : string
    - mysql_catalog_matches_schema : boolean
    - chunking_method : string
        The method used to break the data into smaller chunks for transfer.
        The value can be set to sorted_by_identity_columns or if not set
        the chunking method will be choosen automatically.
    - first_row_is_header : boolean
    - export_action : string
        The kind of export action you want to have the export execute. Set
        to "newsprsht" if you want a new worksheet inside a new
        spreadsheet. Set to "newwksht" if you want a new worksheet inside
        an existing spreadsheet. Set to "updatewksht" if you want to
        overwrite an existing worksheet inside an existing spreadsheet. Set
        to "appendwksht" if you want to append to the end of an existing
        worksheet inside an existing spreadsheet.
    - sql_query : string
        If you are doing a Google Sheet export, this is your SQL query.
    - contact_lists : string
    - soql_query : string

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this import.

hidden : boolean

The hidden status of the object.

archived : string

The archival status of the requested object(s).

put_projects(id, project_id)

Add a JobTypes::Import to a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

put_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_syncs(id, sync_id, source, destination, *, advanced_options='DEFAULT')

Update a sync

Parameters:

id : integer

The ID of the import to fetch.

sync_id : integer

The ID of the sync to fetch.

source : dict:

- path : string
    The path of the dataset to sync from; for a database source,
    schema.tablename. If you are doing a Google Sheet export, this can be
    blank. This is a legacy parameter, it is recommended you use one of the
    following: databaseTable, file, googleWorksheet, salesforce, silverpop
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- file : dict
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.
- silverpop : dict::
    - list_id : integer
        The Silverpop list id.

destination : dict:

- path : string
    The schema.tablename to sync to. If you are doing a Google Sheet
    export, this is the spreadsheet and sheet name separated by a period.
    i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called
    "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy
    parameter, it is recommended you use one of the following:
    databaseTable, googleWorksheet
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.

advanced_options : dict, optional:

- max_errors : integer
- existing_table_rows : string
- distkey : string
- sortkey1 : string
- sortkey2 : string
- column_delimiter : string
- column_overrides : dict
    Hash used for overriding auto-detected names and types, with keys being
    the current name of the column being overridden.
- identity_column : string
- row_chunk_size : integer
- wipe_destination_table : boolean
- truncate_long_lines : boolean
- invalid_char_replacement : string
- verify_table_row_counts : boolean
- partition_column_name : string
- partition_schema_name : string
- partition_table_name : string
- partition_table_partition_column_min_name : string
- partition_table_partition_column_max_name : string
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
- chunking_method : string
    The method used to break the data into smaller chunks for transfer.
    The value can be set to sorted_by_identity_columns or if not set the
    chunking method will be choosen automatically.
- first_row_is_header : boolean
- export_action : string
    The kind of export action you want to have the export execute. Set to
    "newsprsht" if you want a new worksheet inside a new spreadsheet. Set
    to "newwksht" if you want a new worksheet inside an existing
    spreadsheet. Set to "updatewksht" if you want to overwrite an existing
    worksheet inside an existing spreadsheet. Set to "appendwksht" if you
    want to append to the end of an existing worksheet inside an existing
    spreadsheet.
- sql_query : string
    If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
Returns:

id : integer

source : dict:

- id : integer
    The ID of the table or file, if available.
- path : string
    The path of the dataset to sync from; for a database source,
    schema.tablename. If you are doing a Google Sheet export, this can be
    blank. This is a legacy parameter, it is recommended you use one of the
    following: databaseTable, file, googleWorksheet, salesforce, silverpop
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.
- silverpop : dict::
    - list_id : integer
        The Silverpop list id.

destination : dict:

- path : string
    The schema.tablename to sync to. If you are doing a Google Sheet
    export, this is the spreadsheet and sheet name separated by a period.
    i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called
    "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy
    parameter, it is recommended you use one of the following:
    databaseTable, googleWorksheet
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.

advanced_options : dict:

- max_errors : integer
- existing_table_rows : string
- distkey : string
- sortkey1 : string
- sortkey2 : string
- column_delimiter : string
- column_overrides : dict
    Hash used for overriding auto-detected names and types, with keys being
    the current name of the column being overridden.
- identity_column : string
- row_chunk_size : integer
- wipe_destination_table : boolean
- truncate_long_lines : boolean
- invalid_char_replacement : string
- verify_table_row_counts : boolean
- partition_column_name : string
- partition_schema_name : string
- partition_table_name : string
- partition_table_partition_column_min_name : string
- partition_table_partition_column_max_name : string
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
- chunking_method : string
    The method used to break the data into smaller chunks for transfer.
    The value can be set to sorted_by_identity_columns or if not set the
    chunking method will be choosen automatically.
- first_row_is_header : boolean
- export_action : string
    The kind of export action you want to have the export execute. Set to
    "newsprsht" if you want a new worksheet inside a new spreadsheet. Set
    to "newwksht" if you want a new worksheet inside an existing
    spreadsheet. Set to "updatewksht" if you want to overwrite an existing
    worksheet inside an existing spreadsheet. Set to "appendwksht" if you
    want to append to the end of an existing worksheet inside an existing
    spreadsheet.
- sql_query : string
    If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
put_syncs_archive(id, sync_id, *, status='DEFAULT')

Update the archive status of this sync

Parameters:

id : integer

The ID of the import to fetch.

sync_id : integer

The ID of the sync to fetch.

status : boolean, optional

The desired archived status of the sync.

Returns:

id : integer

source : dict:

- id : integer
    The ID of the table or file, if available.
- path : string
    The path of the dataset to sync from; for a database source,
    schema.tablename. If you are doing a Google Sheet export, this can be
    blank. This is a legacy parameter, it is recommended you use one of the
    following: databaseTable, file, googleWorksheet, salesforce, silverpop
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.
- silverpop : dict::
    - list_id : integer
        The Silverpop list id.

destination : dict:

- path : string
    The schema.tablename to sync to. If you are doing a Google Sheet
    export, this is the spreadsheet and sheet name separated by a period.
    i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called
    "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy
    parameter, it is recommended you use one of the following:
    databaseTable, googleWorksheet
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - worksheet : string
        The worksheet tab name.

advanced_options : dict:

- max_errors : integer
- existing_table_rows : string
- distkey : string
- sortkey1 : string
- sortkey2 : string
- column_delimiter : string
- column_overrides : dict
    Hash used for overriding auto-detected names and types, with keys being
    the current name of the column being overridden.
- identity_column : string
- row_chunk_size : integer
- wipe_destination_table : boolean
- truncate_long_lines : boolean
- invalid_char_replacement : string
- verify_table_row_counts : boolean
- partition_column_name : string
- partition_schema_name : string
- partition_table_name : string
- partition_table_partition_column_min_name : string
- partition_table_partition_column_max_name : string
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
- chunking_method : string
    The method used to break the data into smaller chunks for transfer.
    The value can be set to sorted_by_identity_columns or if not set the
    chunking method will be choosen automatically.
- first_row_is_header : boolean
- export_action : string
    The kind of export action you want to have the export execute. Set to
    "newsprsht" if you want a new worksheet inside a new spreadsheet. Set
    to "newwksht" if you want a new worksheet inside an existing
    spreadsheet. Set to "updatewksht" if you want to overwrite an existing
    worksheet inside an existing spreadsheet. Set to "appendwksht" if you
    want to append to the end of an existing worksheet inside an existing
    spreadsheet.
- sql_query : string
    If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string

Jobs

class Jobs(session_kwargs, return_type='civis')

Methods

delete_projects(id, project_id) Remove a Job from a project
delete_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_shares_users(id, user_id) Revoke the permissions a user has on this object
get(id) Show basic job info
get_runs(id, run_id) Check status of a job
list(*[, state, type, q, permission, ...]) List
list_children(id) Show nested tree of children that this job triggers
list_parents(id) Show chain of parents as a list that this job triggers from
list_projects(id, *[, hidden]) List the projects a Job belongs to
list_shares(id) List users and groups permissioned on this object
post_runs(id) Run a job
post_trigger_email(id) Generate and retrieve trigger email address
put_projects(id, project_id) Add a Job to a project
put_shares_groups(id, group_ids, ...[, ...]) Set the permissions groups has on this object
put_shares_users(id, user_ids, ...[, ...]) Set the permissions users have on this object
delete_projects(id, project_id)

Remove a Job from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

delete_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get(id)

Show basic job info

Parameters:

id : integer

The ID for this job.

Returns:

id : integer

name : string

type : string

state : string

Whether the job is idle, queued, running, cancelled, or failed.

created_at : string/date-time

updated_at : string/date-time

runs : list:

Information about the most recent runs of the job.
- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

archived : string

The archival status of the requested object(s).

get_runs(id, run_id)

Check status of a job

Parameters:

id : integer

The ID of the Job.

run_id : integer

The ID of the Run.

Returns:

id : integer

state : string

created_at : string/time

The time that the run was queued.

started_at : string/time

The time that the run started.

finished_at : string/time

The time that the run completed.

error : string

The error message for this run, if present.

list(*, state='DEFAULT', type='DEFAULT', q='DEFAULT', permission='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List

Parameters:

state : string, optional

The job’s state. One or more of queued, running, succeeded, failed, and cancelled. Specify multiple values as a comma-separated list (e.g., “A,B”).

type : string, optional

The job’s type. Specify multiple values as a comma-separated list (e.g., “A,B”).

q : string, optional

Query string to search on the id, name, and job type

permission : string, optional

A permissions string, one of “read”, “write”, or “manage”. Lists only jobs for which the current user has that permission.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

archived : string, optional

The archival status of the requested object(s).

limit : integer, optional

Number of results to return. Defaults to its maximum of 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

name : string

type : string

state : string

Whether the job is idle, queued, running, cancelled, or failed.

created_at : string/date-time

updated_at : string/date-time

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

archived : string

The archival status of the requested object(s).

list_children(id)

Show nested tree of children that this job triggers

Parameters:

id : integer

The ID for this job.

Returns:

id : integer

name : string

type : string

state : string

created_at : string/date-time

updated_at : string/date-time

runs : list:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

children : list

list_parents(id)

Show chain of parents as a list that this job triggers from

Parameters:

id : integer

The ID for this job.

Returns:

id : integer

name : string

type : string

state : string

Whether the job is idle, queued, running, cancelled, or failed.

created_at : string/date-time

updated_at : string/date-time

runs : list:

Information about the most recent runs of the job.
- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

archived : string

The archival status of the requested object(s).

list_projects(id, *, hidden='DEFAULT')

List the projects a Job belongs to

Parameters:

id : integer

The ID of the resource.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

Returns:

id : integer

The ID for this project.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of this project.

description : string

A description of the project

users : list:

Users who can see the project
- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested object(s).

list_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

post_runs(id)

Run a job

Parameters:

id : integer

The ID for this job.

Returns:

id : integer

state : string

created_at : string/time

The time that the run was queued.

started_at : string/time

The time that the run started.

finished_at : string/time

The time that the run completed.

error : string

The error message for this run, if present.

post_trigger_email(id)

Generate and retrieve trigger email address

Parameters:

id : integer

The ID for this job.

Returns:

trigger_email : string

Email address which may be used to trigger this job to run.

put_projects(id, project_id)

Add a Job to a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

put_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Match_Targets

civis.resources._resources.Match_Targets

alias of MatchTargets

Media

class Media(session_kwargs, return_type='civis')

Methods

delete_optimizations_runs(id, run_id) Cancel a run
delete_optimizations_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_optimizations_shares_users(id, user_id) Revoke the permissions a user has on this object
delete_spot_orders_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_spot_orders_shares_users(id, user_id) Revoke the permissions a user has on this object
get_optimizations(id) Show a single optimization
get_optimizations_runs(id, run_id) Check status of a run
get_spot_orders(id) Show a single spot order
list_dmas(*[, name, number]) List all Designated Market Areas
list_optimizations(*[, archived, limit, ...]) List all optimizations
list_optimizations_runs(id, *[, limit, ...]) List runs for the given optimization
list_optimizations_runs_logs(id, run_id, *) Get the logs for a run
list_optimizations_shares(id) List users and groups permissioned on this object
list_ratecards(*[, filename, dma_number]) List all ratecards
list_spot_orders(*[, id, archived]) List all spot orders
list_spot_orders_shares(id) List users and groups permissioned on this object
list_targets(*[, name, identifier, data_source]) List all Media Targets
patch_optimizations(id, *[, name, runs]) Edit an existing optimization
post_optimizations(runs, *[, name]) Create a new optimization
post_optimizations_clone(id) Clone an existing optimization
post_optimizations_runs(id) Start a run
post_spot_orders(*[, body]) Create a spot order
put_optimizations_archive(id, status) Update the archive status of this object
put_optimizations_shares_groups(id, ...[, ...]) Set the permissions groups has on this object
put_optimizations_shares_users(id, user_ids, ...) Set the permissions users have on this object
put_spot_orders(id, *[, body]) Edit the specified spot order
put_spot_orders_archive(id, status) Update the archive status of this object
put_spot_orders_shares_groups(id, group_ids, ...) Set the permissions groups has on this object
put_spot_orders_shares_users(id, user_ids, ...) Set the permissions users have on this object
delete_optimizations_runs(id, run_id)

Cancel a run

Parameters:

id : integer

The ID of the optimization.

run_id : integer

The ID of the run.

Returns:

None

Response code 202: success

delete_optimizations_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_optimizations_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

delete_spot_orders_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_spot_orders_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get_optimizations(id)

Show a single optimization

Parameters:

id : integer

The optimization ID.

Returns:

id : integer

The optimization ID.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of the optimization.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

spot_order_id : integer

The ID for the spot order produced by the optimization.

archived : string

The archival status of the requested object(s).

report_link : string

A link to the visual report for the optimization.

spot_order_link : string

A link to the json version of the spot order.

file_links : list

Links to the csv and xml versions of the spot order.

runs : list:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.
get_optimizations_runs(id, run_id)

Check status of a run

Parameters:

id : integer

The ID of the optimization.

run_id : integer

The ID of the run.

Returns:

id : integer

The ID of the run.

optimization_id : integer

The ID of the optimization.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

get_spot_orders(id)

Show a single spot order

Parameters:

id : integer

The ID for the spot order.

Returns:

id : integer

The ID for the spot order.

archived : string

The archival status of the requested object(s).

csv_s3_uri : string

S3 URI for the spot order CSV file.

json_s3_uri : string

S3 URI for the spot order JSON file.

xml_archive_s3_uri : string

S3 URI for the spot order XML archive.

last_transform_job_id : integer

ID of the spot order transformation job.

list_dmas(*, name='DEFAULT', number='DEFAULT')

List all Designated Market Areas

Parameters:

name : string, optional

If specified, will be used to filter the DMAs returned. Substring matching is supported with “%” and “*” wildcards (e.g., “name=%region%” will return both “region1” and “my region”).

number : integer, optional

If specified, will be used to filter the DMAS by number.

Returns:

name : string

Name for the DMA region.

number : integer

Identifier number for a DMA.

list_optimizations(*, archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List all optimizations

Parameters:

archived : string, optional

The archival status of the requested object(s).

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to created_at. Must be one of: created_at, author, name.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The optimization ID.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of the optimization.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

spot_order_id : integer

The ID for the spot order produced by the optimization.

archived : string

The archival status of the requested object(s).

list_optimizations_runs(id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List runs for the given optimization

Parameters:

id : integer

The ID of the optimization.

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 100.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to id. Must be one of: id.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of the run.

optimization_id : integer

The ID of the optimization.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

list_optimizations_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')

Get the logs for a run

Parameters:

id : integer

The ID of the optimization.

run_id : integer

The ID of the run.

last_id : integer, optional

The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.

limit : integer, optional

The maximum number of log messages to return. Default of 10000.

Returns:

id : integer

The ID of the log.

created_at : string/date-time

The time the log was created.

message : string

The log message.

level : string

The level of the log. One of unknown,fatal,error,warn,info,debug.

list_optimizations_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_ratecards(*, filename='DEFAULT', dma_number='DEFAULT')

List all ratecards

Parameters:

filename : string, optional

If specified, will be used to filter the ratecards returned. Substring matching is supported with “%” and “*” wildcards (e.g., “filename=%ratecard%” will return both “ratecard 1” and “my ratecard”).

dma_number : integer, optional

If specified, will be used to filter the ratecards by DMA.

Returns:

id : integer

The ratecard ID.

filename : string

Name of the ratecard file.

start_on : string/date

First day to which the ratecard applies.

end_on : string/date

Last day to which the ratecard applies.

dma_number : integer

Number of the DMA associated with the ratecard.

list_spot_orders(*, id='DEFAULT', archived='DEFAULT')

List all spot orders

Parameters:

id : integer, optional

The ID for the spot order.

archived : string, optional

The archival status of the requested object(s).

Returns:

id : integer

The ID for the spot order.

archived : string

The archival status of the requested object(s).

list_spot_orders_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_targets(*, name='DEFAULT', identifier='DEFAULT', data_source='DEFAULT')

List all Media Targets

Parameters:

name : string, optional

The name of the target.

identifier : string, optional

A unique identifier for this target.

data_source : string, optional

The source of viewership data for this target.

Returns:

name : string

The name of the target.

identifier : string

A unique identifier for this target.

data_source : string

The source of viewership data for this target.

patch_optimizations(id, *, name='DEFAULT', runs='DEFAULT')

Edit an existing optimization

Parameters:

id : integer

The optimization ID.

name : string, optional

The name of the optimization.

runs : list, optional:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.
Returns:

id : integer

The optimization ID.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of the optimization.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

spot_order_id : integer

The ID for the spot order produced by the optimization.

archived : string

The archival status of the requested object(s).

report_link : string

A link to the visual report for the optimization.

spot_order_link : string

A link to the json version of the spot order.

file_links : list

Links to the csv and xml versions of the spot order.

runs : list:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.
post_optimizations(runs, *, name='DEFAULT')

Create a new optimization

Parameters:

runs : list:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.

name : string, optional

The name of the optimization.

Returns:

id : integer

The optimization ID.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of the optimization.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

spot_order_id : integer

The ID for the spot order produced by the optimization.

archived : string

The archival status of the requested object(s).

report_link : string

A link to the visual report for the optimization.

spot_order_link : string

A link to the json version of the spot order.

file_links : list

Links to the csv and xml versions of the spot order.

runs : list:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.
post_optimizations_clone(id)

Clone an existing optimization

Parameters:

id : integer

The optimization ID.

Returns:

id : integer

The optimization ID.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of the optimization.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

spot_order_id : integer

The ID for the spot order produced by the optimization.

archived : string

The archival status of the requested object(s).

report_link : string

A link to the visual report for the optimization.

spot_order_link : string

A link to the json version of the spot order.

file_links : list

Links to the csv and xml versions of the spot order.

runs : list:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.
post_optimizations_runs(id)

Start a run

Parameters:

id : integer

The ID of the optimization.

Returns:

id : integer

The ID of the run.

optimization_id : integer

The ID of the optimization.

state : string

The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started at.

finished_at : string/time

The time the last run completed.

error : string

The error, if any, returned by the run.

post_spot_orders(*, body='DEFAULT')

Create a spot order

Parameters:

body : string, optional

CSV body of a spot order.

Returns:

id : integer

The ID for the spot order.

archived : string

The archival status of the requested object(s).

csv_s3_uri : string

S3 URI for the spot order CSV file.

json_s3_uri : string

S3 URI for the spot order JSON file.

xml_archive_s3_uri : string

S3 URI for the spot order XML archive.

last_transform_job_id : integer

ID of the spot order transformation job.

put_optimizations_archive(id, status)

Update the archive status of this object

Parameters:

id : integer

The ID of the object.

status : boolean

The desired archived status of the object.

Returns:

id : integer

The optimization ID.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of the optimization.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

spot_order_id : integer

The ID for the spot order produced by the optimization.

archived : string

The archival status of the requested object(s).

report_link : string

A link to the visual report for the optimization.

spot_order_link : string

A link to the json version of the spot order.

file_links : list

Links to the csv and xml versions of the spot order.

runs : list:

The runs of the optimization.
- market_id : integer
    The market ID.
- start_date : string/date
    The start date for the media run.
- end_date : string/date
    The end date for the media run.
- syscodes : list
    The syscodes for the media run.
- rate_cards : list
    The ratecards for the media run.
- constraints : list::
    The constraints for the media run.
    - targets : list
        The targets to constrain.
    - budget : number/float
        The maximum budget for these targets.
    - frequency : integer
        The maximum frequency for these targets.
put_optimizations_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_optimizations_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_spot_orders(id, *, body='DEFAULT')

Edit the specified spot order

Parameters:

id : integer

The ID for the spot order.

body : string, optional

CSV body of a spot order.

Returns:

id : integer

The ID for the spot order.

archived : string

The archival status of the requested object(s).

csv_s3_uri : string

S3 URI for the spot order CSV file.

json_s3_uri : string

S3 URI for the spot order JSON file.

xml_archive_s3_uri : string

S3 URI for the spot order XML archive.

last_transform_job_id : integer

ID of the spot order transformation job.

put_spot_orders_archive(id, status)

Update the archive status of this object

Parameters:

id : integer

The ID of the object.

status : boolean

The desired archived status of the object.

Returns:

id : integer

The ID for the spot order.

archived : string

The archival status of the requested object(s).

csv_s3_uri : string

S3 URI for the spot order CSV file.

json_s3_uri : string

S3 URI for the spot order JSON file.

xml_archive_s3_uri : string

S3 URI for the spot order XML archive.

last_transform_job_id : integer

ID of the spot order transformation job.

put_spot_orders_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_spot_orders_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Models

class Models(session_kwargs, return_type='civis')

Methods

delete_builds(id, build_id) Cancel a build
delete_projects(id, project_id) Remove a models from a project
delete_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_shares_users(id, user_id) Revoke the permissions a user has on this object
get(id) Retrieve model configuration
get_builds(id, build_id) Check status of a build
list(*[, model_name, training_table_name, ...]) List
list_builds(id, *[, limit, page_num, order, ...]) List builds for the given model
list_builds_logs(id, build_id, *[, last_id, ...]) Get the logs for a build
list_projects(id, *[, hidden]) List the projects a models belongs to
list_schedules(id) Show the model build schedule
list_shares(id) List users and groups permissioned on this object
list_types() List all available model types
patch(id, *[, table_name, database_id, ...]) Update model configuration
post(*[, table_name, database_id, ...]) Create new configuration for a model
post_builds(id) Start a build
put_archive(id, status) Update the archive status of this object
put_predictions(id, table_name, primary_key, *) Add a table on which to apply the predictive model
put_projects(id, project_id) Add a models to a project
put_schedules(id, schedule) Schedule the model build
put_shares_groups(id, group_ids, ...[, ...]) Set the permissions groups has on this object
put_shares_users(id, user_ids, ...[, ...]) Set the permissions users have on this object
delete_builds(id, build_id)

Cancel a build

Parameters:

id : integer

The ID of the model.

build_id : integer

The ID of the build.

Returns:

None

Response code 202: success

delete_projects(id, project_id)

Remove a models from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

delete_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get(id)

Retrieve model configuration

Parameters:

id : integer

The ID of the model.

Returns:

id : integer

The ID of the model.

table_name : string

The qualified name of the table containing the training set from which to build the model.

database_id : integer

The ID of the database holding the training set table used to build the model.

credential_id : integer

The ID of the credential used to read the target table. Defaults to the user’s default credential.

model_name : string

The name of the model.

description : string

A description of the model.

interaction_terms : boolean

Whether to search for interaction terms.

box_cox_transformation : boolean

Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

model_type_id : integer

The ID of the model’s type.

primary_key : string

The unique ID (primary key) of the training dataset.

dependent_variable : string

The dependent variable of the training dataset.

dependent_variable_order : list

The order of dependent variables, especially useful for Ordinal Modeling.

excluded_columns : list

A list of columns which will be considered ineligible to be independent variables.

limiting_sql : string

A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

active_build_id : integer

The ID of the current active build, the build used to score predictions.

cross_validation_parameters : dict

Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

number_of_folds : integer

Number of folds for cross validation. Default value is 5.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

The ID of the parent job that will trigger this model.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

time_zone : string

The time zone of this model.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

created_at : string/date-time

The time the model was created.

updated_at : string/date-time

The time the model was updated.

current_build_state : string

The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

current_build_exception : string

Exception message, if applicable, of the current model build.

builds : list:

A list of trained models available for making predictions.
- id : integer
    The ID of the model build.
- name : string
    The name of the model build.
- created_at : string
    The time the model build was created.
- description : string
    A description of the model build.
- root_mean_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- r_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- roc_auc : number/float
    A key metric for binary, multinomial, and ordinal models. Nil for other
    model types.

predictions : list:

The tables upon which the model will be applied.
- id : integer
    The ID of the model to which to apply the prediction.
- table_name : string
    The qualified name of the table on which to apply the predictive model.
- primary_key : list
    The primary key or composite keys of the table being predicted.
- limiting_sql : string
    A SQL WHERE clause used to scope the rows to be predicted.
- output_table : string
    The qualified name of the table to be created which will contain the
    model's predictions.
- schedule : dict::
    - scheduled : boolean
        If the object is scheduled
    - scheduled_days : list
        Day based on numeric value starting at 0 for Sunday
    - scheduled_hours : list
        Hours of the day it is scheduled on
    - scheduled_minutes : list
        Minutes of the day it is scheduled on
    - scheduled_runs_per_hour : integer
        Alternative to scheduled minutes, number of times to run per hour
- state : string
    The status of the prediction. One of: "succeeded", "failed", "queued",
    or "running,"or "idle", if no build has been attempted.

last_output_location : string

The output JSON for the last build.

archived : string

The archival status of the requested object(s).

get_builds(id, build_id)

Check status of a build

Parameters:

id : integer

The ID of the model.

build_id : integer

The ID of the build.

Returns:

id : integer

The ID of the model build.

state : string

The state of the model build.one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

error : string

The error, if any, returned by the build.

name : string

The name of the model build.

created_at : string

The time the model build was created.

description : string

A description of the model build.

root_mean_squared_error : number/float

A key metric for continuous models. Nil for other model types.

r_squared_error : number/float

A key metric for continuous models. Nil for other model types.

roc_auc : number/float

A key metric for binary, multinomial, and ordinal models. Nil for other model types.

transformation_metadata : string

A string representing the full JSON output of the metadata for transformation of column names

output : string

A string representing the JSON output for the specified build. Only present when smaller than 10KB in size.

output_location : string

A URL representing the location of the full JSON output for the specified build.The URL link will be valid for 5 minutes.

list(*, model_name='DEFAULT', training_table_name='DEFAULT', dependent_variable='DEFAULT', author='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List

Parameters:

model_name : string, optional

If specified, will be used to filter the models returned. Substring matching is supported. (e.g., “modelName=model” will return both “model1” and “my model”).

training_table_name : string, optional

If specified, will be used to filter the models returned by the training dataset table name. Substring matching is supported. (e.g., “trainingTableName=table” will return both “table1” and “my_table”).

dependent_variable : string, optional

If specified, will be used to filter the models returned by the dependent variable column name. Substring matching is supported. (e.g., “dependentVariable=predictor” will return both “predictor” and “my predictor”).

author : string, optional

If specified, return models from this author. It accepts a comma-separated list of author ids.

status : string, optional

If specified, returns models with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

archived : string, optional

The archival status of the requested object(s).

limit : integer, optional

Number of results to return. Defaults to its maximum of 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at, last_run.updated_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of the model.

table_name : string

The qualified name of the table containing the training set from which to build the model.

database_id : integer

The ID of the database holding the training set table used to build the model.

credential_id : integer

The ID of the credential used to read the target table. Defaults to the user’s default credential.

model_name : string

The name of the model.

description : string

A description of the model.

interaction_terms : boolean

Whether to search for interaction terms.

box_cox_transformation : boolean

Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

model_type_id : integer

The ID of the model’s type.

primary_key : string

The unique ID (primary key) of the training dataset.

dependent_variable : string

The dependent variable of the training dataset.

dependent_variable_order : list

The order of dependent variables, especially useful for Ordinal Modeling.

excluded_columns : list

A list of columns which will be considered ineligible to be independent variables.

limiting_sql : string

A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

cross_validation_parameters : dict

Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

number_of_folds : integer

Number of folds for cross validation. Default value is 5.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

The ID of the parent job that will trigger this model.

time_zone : string

The time zone of this model.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

created_at : string/date-time

The time the model was created.

updated_at : string/date-time

The time the model was updated.

current_build_state : string

The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

current_build_exception : string

Exception message, if applicable, of the current model build.

builds : list:

A list of trained models available for making predictions.
- id : integer
    The ID of the model build.
- name : string
    The name of the model build.
- created_at : string
    The time the model build was created.
- description : string
    A description of the model build.
- root_mean_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- r_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- roc_auc : number/float
    A key metric for binary, multinomial, and ordinal models. Nil for other
    model types.

predictions : list:

The tables upon which the model will be applied.
- id : integer
    The ID of the model to which to apply the prediction.
- table_name : string
    The qualified name of the table on which to apply the predictive model.
- primary_key : list
    The primary key or composite keys of the table being predicted.
- limiting_sql : string
    A SQL WHERE clause used to scope the rows to be predicted.
- output_table : string
    The qualified name of the table to be created which will contain the
    model's predictions.
- state : string
    The status of the prediction. One of: "succeeded", "failed", "queued",
    or "running,"or "idle", if no build has been attempted.

last_output_location : string

The output JSON for the last build.

archived : string

The archival status of the requested object(s).

list_builds(id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List builds for the given model

Parameters:

id : integer

The ID of the model.

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 100.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to id. Must be one of: id.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of the model build.

state : string

The state of the model build.one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

error : string

The error, if any, returned by the build.

name : string

The name of the model build.

created_at : string

The time the model build was created.

description : string

A description of the model build.

root_mean_squared_error : number/float

A key metric for continuous models. Nil for other model types.

r_squared_error : number/float

A key metric for continuous models. Nil for other model types.

roc_auc : number/float

A key metric for binary, multinomial, and ordinal models. Nil for other model types.

transformation_metadata : string

A string representing the full JSON output of the metadata for transformation of column names

output : string

A string representing the JSON output for the specified build. Only present when smaller than 10KB in size.

output_location : string

A URL representing the location of the full JSON output for the specified build.The URL link will be valid for 5 minutes.

list_builds_logs(id, build_id, *, last_id='DEFAULT', limit='DEFAULT')

Get the logs for a build

Parameters:

id : integer

The ID of the model.

build_id : integer

The ID of the build.

last_id : integer, optional

The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.

limit : integer, optional

The maximum number of log messages to return. Default of 10000.

Returns:

id : integer

The ID of the log.

created_at : string/date-time

The time the log was created.

message : string

The log message.

level : string

The level of the log. One of unknown,fatal,error,warn,info,debug.

list_projects(id, *, hidden='DEFAULT')

List the projects a models belongs to

Parameters:

id : integer

The ID of the resource.

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

Returns:

id : integer

The ID for this project.

author : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

name : string

The name of this project.

description : string

A description of the project

users : list:

Users who can see the project
- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested object(s).

list_schedules(id)

Show the model build schedule

Parameters:

id : integer

The ID of the model associated with this schedule.

Returns:

id : integer

The ID of the model associated with this schedule.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour
list_shares(id)

List users and groups permissioned on this object

Parameters:

id : integer

The ID of the object.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_types()

List all available model types

Returns:

id : integer

The ID of the model type.

algorithm : string

The name of the algorithm used to train the model.

dv_type : string

The type of dependent variable predicted by the model.

fint_allowed : boolean

Whether this model type supports searching for interaction terms.

patch(id, *, table_name='DEFAULT', database_id='DEFAULT', credential_id='DEFAULT', model_name='DEFAULT', description='DEFAULT', interaction_terms='DEFAULT', box_cox_transformation='DEFAULT', model_type_id='DEFAULT', primary_key='DEFAULT', dependent_variable='DEFAULT', dependent_variable_order='DEFAULT', excluded_columns='DEFAULT', limiting_sql='DEFAULT', active_build_id='DEFAULT', cross_validation_parameters='DEFAULT', number_of_folds='DEFAULT', notifications='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', time_zone='DEFAULT')

Update model configuration

Parameters:

id : integer

The ID of the model.

table_name : string, optional

The qualified name of the table containing the training set from which to build the model.

database_id : integer, optional

The ID of the database holding the training set table used to build the model.

credential_id : integer, optional

The ID of the credential used to read the target table. Defaults to the user’s default credential.

model_name : string, optional

The name of the model.

description : string, optional

A description of the model.

interaction_terms : boolean, optional

Whether to search for interaction terms.

box_cox_transformation : boolean, optional

Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

model_type_id : integer, optional

The ID of the model’s type.

primary_key : string, optional

The unique ID (primary key) of the training dataset.

dependent_variable : string, optional

The dependent variable of the training dataset.

dependent_variable_order : list, optional

The order of dependent variables, especially useful for Ordinal Modeling.

excluded_columns : list, optional

A list of columns which will be considered ineligible to be independent variables.

limiting_sql : string, optional

A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

active_build_id : integer, optional

The ID of the current active build, the build used to score predictions.

cross_validation_parameters : dict, optional

Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

number_of_folds : integer, optional

Number of folds for cross validation. Default value is 5.

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer, optional

The ID of the parent job that will trigger this model.

time_zone : string, optional

The time zone of this model.

Returns:

None

Response code 204: success

post(*, table_name='DEFAULT', database_id='DEFAULT', credential_id='DEFAULT', model_name='DEFAULT', description='DEFAULT', interaction_terms='DEFAULT', box_cox_transformation='DEFAULT', model_type_id='DEFAULT', primary_key='DEFAULT', dependent_variable='DEFAULT', dependent_variable_order='DEFAULT', excluded_columns='DEFAULT', limiting_sql='DEFAULT', active_build_id='DEFAULT', cross_validation_parameters='DEFAULT', number_of_folds='DEFAULT', notifications='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT')

Create new configuration for a model

Parameters:

table_name : string, optional

The qualified name of the table containing the training set from which to build the model.

database_id : integer, optional

The ID of the database holding the training set table used to build the model.

credential_id : integer, optional

The ID of the credential used to read the target table. Defaults to the user’s default credential.

model_name : string, optional

The name of the model.

description : string, optional

A description of the model.

interaction_terms : boolean, optional

Whether to search for interaction terms.

box_cox_transformation : boolean, optional

Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

model_type_id : integer, optional

The ID of the model’s type.

primary_key : string, optional

The unique ID (primary key) of the training dataset.

dependent_variable : string, optional

The dependent variable of the training dataset.

dependent_variable_order : list, optional

The order of dependent variables, especially useful for Ordinal Modeling.

excluded_columns : list, optional

A list of columns which will be considered ineligible to be independent variables.

limiting_sql : string, optional

A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

active_build_id : integer, optional

The ID of the current active build, the build used to score predictions.

cross_validation_parameters : dict, optional

Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

number_of_folds : integer, optional

Number of folds for cross validation. Default value is 5.

notifications : dict, optional:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer, optional

The ID of the parent job that will trigger this model.

time_zone : string, optional

The time zone of this model.

hidden : boolean, optional

The hidden status of the object.

Returns:

id : integer

The ID of the model.

table_name : string

The qualified name of the table containing the training set from which to build the model.

database_id : integer

The ID of the database holding the training set table used to build the model.

credential_id : integer

The ID of the credential used to read the target table. Defaults to the user’s default credential.

model_name : string

The name of the model.

description : string

A description of the model.

interaction_terms : boolean

Whether to search for interaction terms.

box_cox_transformation : boolean

Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

model_type_id : integer

The ID of the model’s type.

primary_key : string

The unique ID (primary key) of the training dataset.

dependent_variable : string

The dependent variable of the training dataset.

dependent_variable_order : list

The order of dependent variables, especially useful for Ordinal Modeling.

excluded_columns : list

A list of columns which will be considered ineligible to be independent variables.

limiting_sql : string

A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

active_build_id : integer

The ID of the current active build, the build used to score predictions.

cross_validation_parameters : dict

Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

number_of_folds : integer

Number of folds for cross validation. Default value is 5.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

The ID of the parent job that will trigger this model.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

time_zone : string

The time zone of this model.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

created_at : string/date-time

The time the model was created.

updated_at : string/date-time

The time the model was updated.

current_build_state : string

The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

current_build_exception : string

Exception message, if applicable, of the current model build.

builds : list:

A list of trained models available for making predictions.
- id : integer
    The ID of the model build.
- name : string
    The name of the model build.
- created_at : string
    The time the model build was created.
- description : string
    A description of the model build.
- root_mean_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- r_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- roc_auc : number/float
    A key metric for binary, multinomial, and ordinal models. Nil for other
    model types.

predictions : list:

The tables upon which the model will be applied.
- id : integer
    The ID of the model to which to apply the prediction.
- table_name : string
    The qualified name of the table on which to apply the predictive model.
- primary_key : list
    The primary key or composite keys of the table being predicted.
- limiting_sql : string
    A SQL WHERE clause used to scope the rows to be predicted.
- output_table : string
    The qualified name of the table to be created which will contain the
    model's predictions.
- schedule : dict::
    - scheduled : boolean
        If the object is scheduled
    - scheduled_days : list
        Day based on numeric value starting at 0 for Sunday
    - scheduled_hours : list
        Hours of the day it is scheduled on
    - scheduled_minutes : list
        Minutes of the day it is scheduled on
    - scheduled_runs_per_hour : integer
        Alternative to scheduled minutes, number of times to run per hour
- state : string
    The status of the prediction. One of: "succeeded", "failed", "queued",
    or "running,"or "idle", if no build has been attempted.

last_output_location : string

The output JSON for the last build.

archived : string

The archival status of the requested object(s).

post_builds(id)

Start a build

Parameters:

id : integer

The ID of the model.

Returns:

id : integer

The ID of the model build.

state : string

The state of the model build.one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

error : string

The error, if any, returned by the build.

name : string

The name of the model build.

created_at : string

The time the model build was created.

description : string

A description of the model build.

root_mean_squared_error : number/float

A key metric for continuous models. Nil for other model types.

r_squared_error : number/float

A key metric for continuous models. Nil for other model types.

roc_auc : number/float

A key metric for binary, multinomial, and ordinal models. Nil for other model types.

transformation_metadata : string

A string representing the full JSON output of the metadata for transformation of column names

output : string

A string representing the JSON output for the specified build. Only present when smaller than 10KB in size.

output_location : string

A URL representing the location of the full JSON output for the specified build.The URL link will be valid for 5 minutes.

put_archive(id, status)

Update the archive status of this object

Parameters:

id : integer

The ID of the object.

status : boolean

The desired archived status of the object.

Returns:

id : integer

The ID of the model.

table_name : string

The qualified name of the table containing the training set from which to build the model.

database_id : integer

The ID of the database holding the training set table used to build the model.

credential_id : integer

The ID of the credential used to read the target table. Defaults to the user’s default credential.

model_name : string

The name of the model.

description : string

A description of the model.

interaction_terms : boolean

Whether to search for interaction terms.

box_cox_transformation : boolean

Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

model_type_id : integer

The ID of the model’s type.

primary_key : string

The unique ID (primary key) of the training dataset.

dependent_variable : string

The dependent variable of the training dataset.

dependent_variable_order : list

The order of dependent variables, especially useful for Ordinal Modeling.

excluded_columns : list

A list of columns which will be considered ineligible to be independent variables.

limiting_sql : string

A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

active_build_id : integer

The ID of the current active build, the build used to score predictions.

cross_validation_parameters : dict

Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

number_of_folds : integer

Number of folds for cross validation. Default value is 5.

notifications : dict:

- urls : list
    URLs to receive a POST request at job completion
- success_email_subject : string
    Custom subject line for success e-mail.
- success_email_body : string
    Custom body text for success e-mail, written in Markdown.
- success_email_addresses : list
    Addresses to notify by e-mail when the job completes successfully.
- success_email_from_name : string
    Name from which success emails are sent; defaults to "Civis."
- success_email_reply_to : string
    Address for replies to success emails; defaults to the author of the
    job.
- failure_email_addresses : list
    Addresses to notify by e-mail when the job fails.
- stall_warning_minutes : integer
    Stall warning emails will be sent after this amount of minutes.
- success_on : boolean
    If success email notifications are on.
- failure_on : boolean
    If failure email notifications are on.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

parent_id : integer

The ID of the parent job that will trigger this model.

running_as : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

time_zone : string

The time zone of this model.

last_run : dict:

- id : integer
- state : string
- created_at : string/time
    The time that the run was queued.
- started_at : string/time
    The time that the run started.
- finished_at : string/time
    The time that the run completed.
- error : string
    The error message for this run, if present.

hidden : boolean

The hidden status of the object.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

created_at : string/date-time

The time the model was created.

updated_at : string/date-time

The time the model was updated.

current_build_state : string

The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

current_build_exception : string

Exception message, if applicable, of the current model build.

builds : list:

A list of trained models available for making predictions.
- id : integer
    The ID of the model build.
- name : string
    The name of the model build.
- created_at : string
    The time the model build was created.
- description : string
    A description of the model build.
- root_mean_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- r_squared_error : number/float
    A key metric for continuous models. Nil for other model types.
- roc_auc : number/float
    A key metric for binary, multinomial, and ordinal models. Nil for other
    model types.

predictions : list:

The tables upon which the model will be applied.
- id : integer
    The ID of the model to which to apply the prediction.
- table_name : string
    The qualified name of the table on which to apply the predictive model.
- primary_key : list
    The primary key or composite keys of the table being predicted.
- limiting_sql : string
    A SQL WHERE clause used to scope the rows to be predicted.
- output_table : string
    The qualified name of the table to be created which will contain the
    model's predictions.
- schedule : dict::
    - scheduled : boolean
        If the object is scheduled
    - scheduled_days : list
        Day based on numeric value starting at 0 for Sunday
    - scheduled_hours : list
        Hours of the day it is scheduled on
    - scheduled_minutes : list
        Minutes of the day it is scheduled on
    - scheduled_runs_per_hour : integer
        Alternative to scheduled minutes, number of times to run per hour
- state : string
    The status of the prediction. One of: "succeeded", "failed", "queued",
    or "running,"or "idle", if no build has been attempted.

last_output_location : string

The output JSON for the last build.

archived : string

The archival status of the requested object(s).

put_predictions(id, table_name, primary_key, *, limiting_sql='DEFAULT', output_table='DEFAULT', schedule='DEFAULT')

Add a table on which to apply the predictive model

Parameters:

id : integer

The ID of the model to which to apply the prediction.

table_name : string

The qualified name of the table on which to apply the predictive model.

primary_key : list

The primary key or composite keys of the table being predicted.

limiting_sql : string, optional

A SQL WHERE clause used to scope the rows to be predicted.

output_table : string, optional

The qualified name of the table to be created which will contain the model’s predictions.

schedule : dict, optional:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour
Returns:

id : integer

The ID of the model to which to apply the prediction.

table_name : string

The qualified name of the table on which to apply the predictive model.

primary_key : list

The primary key or composite keys of the table being predicted.

limiting_sql : string

A SQL WHERE clause used to scope the rows to be predicted.

output_table : string

The qualified name of the table to be created which will contain the model’s predictions.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour

state : string

The status of the prediction. One of: “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

put_projects(id, project_id)

Add a models to a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

put_schedules(id, schedule)

Schedule the model build

Parameters:

id : integer

The ID of the model associated with this schedule.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour
Returns:

id : integer

The ID of the model associated with this schedule.

schedule : dict:

- scheduled : boolean
    If the object is scheduled
- scheduled_days : list
    Day based on numeric value starting at 0 for Sunday
- scheduled_hours : list
    Hours of the day it is scheduled on
- scheduled_minutes : list
    Minutes of the day it is scheduled on
- scheduled_runs_per_hour : integer
    Alternative to scheduled minutes, number of times to run per hour
put_shares_groups(id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions groups has on this object

Parameters:

id : integer

ID of the resource to be shared

group_ids : list

An array of one or more group IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_shares_users(id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')

Set the permissions users have on this object

Parameters:

id : integer

ID of the resource to be shared

user_ids : list

An array of one or more user IDs

permission_level : string

Options are: “read”, “write”, or “manage”

share_email_body : string, optional

Custom body text for e-mail sent on a share.

send_shared_email : boolean, optional

Send email to the recipients of a share.

Returns:

readers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

writers : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

owners : dict:

- users : list::
    - id : integer
    - name : string
- groups : list::
    - id : integer
    - name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

Notebooks

class Notebooks(session_kwargs, return_type='civis')

Methods

delete_deployments(notebook_id, deployment_id) Delete a Notebook deployment
delete_projects(id, project_id) Remove a Notebook from a project
delete_shares_groups(id, group_id) Revoke the permissions a group has on this object
delete_shares_users(id, user_id) Revoke the permissions a user has on this object
get(id) Get a Notebook
get_deployments(notebook_id, deployment_id) Get details about a Notebook deployment
list(*[, hidden, archived, author, status, ...]) List Notebooks
list_deployments(notebook_id, *[, ...]) List deployments for a Notebook
list_projects(id, *[, hidden]) List the projects a Notebook belongs to
list_shares(id) List users and groups permissioned on this object
list_update_links(id) Get URLs to update notebook
patch(id, *[, name, language, description, ...]) Update some attributes of this Notebook
post(*[, name, language, description, ...]) Create a Notebook
post_clone(id) Clone this notebook
post_deployments(notebook_id, *[, ...]) Deploy a Notebook
put(id, *[, name, language, description, ...]) Replace all attributes of this Notebook
put_archive(id, status) Update the archive status of this object
put_projects(id, project_id) Add a Notebook to a project
put_shares_groups(id, group_ids, ...[, ...]) Set the permissions groups has on this object
put_shares_users(id, user_ids, ...[, ...]) Set the permissions users have on this object
delete_deployments(notebook_id, deployment_id)

Delete a Notebook deployment

Parameters:

notebook_id : integer

The ID of the owning Notebook

deployment_id : integer

The ID for this deployment

Returns:

None

Response code 204: success

delete_projects(id, project_id)

Remove a Notebook from a project

Parameters:

id : integer

ID of the resource

project_id : integer

The ID of the project

Returns:

None

Response code 204: success

delete_shares_groups(id, group_id)

Revoke the permissions a group has on this object

Parameters:

id : integer

ID of the resource to be revoked

group_id : integer

ID of the group

Returns:

None

Response code 204: success

delete_shares_users(id, user_id)

Revoke the permissions a user has on this object

Parameters:

id : integer

ID of the resource to be revoked

user_id : integer

ID of the user

Returns:

None

Response code 204: success

get(id)

Get a Notebook

Parameters:

id : integer

Returns:

id : integer

The ID for this notebook.

name : string

The name of this notebook.

language : string

The kernel language of this notebook.

description : string

The description of this notebook.

notebook_url : string

Time-limited URL to get the .ipynb file for this notebook.

notebook_preview_url : string

Time-limited URL to get the .htm preview file for this notebook.

requirements_url : string

Time-limited URL to get the requirements.txt file for this notebook.

file_id : string

The file ID for the S3 file containing the .ipynb file.

requirements_file_id : string

The file ID for the S3 file containing the requirements.txt file.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

docker_image_name : string

The name of the docker image to pull from DockerHub.

docker_image_tag : string

The tag of the docker image to pull from DockerHub (default: latest).

memory : integer

The amount of memory allocated to the notebook.

cpu : integer

The amount of cpu allocated to the the notebook.

created_at : string/time

updated_at : string/time

most_recent_deployment : dict:

- deployment_id : integer
    The ID for this deployment.
- user_id : integer
    The ID of the owner.
- host : string
    Domain of the deployment.
- name : string
    Name of the deployment.
- docker_image_name : string
    The name of the docker image to pull from DockerHub.
- docker_image_tag : string
    The tag of the docker image to pull from DockerHub (default: latest).
- display_url : string
    URL that displays the deployed platform object and includes auth token.
- memory : integer
    The memory allocated to the deployment.
- cpu : integer
    The cpu allocated to the deployment.
- state : string
    The state of the deployment.
- state_message : string
    A detailed description of the state.
- created_at : string/time
- updated_at : string/time
- published : boolean
- notebook_id : integer
    The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

git_url : string

The URL of the repository that will be cloned.

git_branch : string

The name of the branch that will be cloned.

git_file : string

The name of the notebook file within a repository that will be included in the deployment.

environment_variables : dict

Environment variables to be passed into the Notebook.

idle_timeout : integer

How long the notebook will stay alive without any kernel activity.

archived : string

The archival status of the requested object(s).

hidden : boolean

The hidden status of the object.

get_deployments(notebook_id, deployment_id)

Get details about a Notebook deployment

Parameters:

notebook_id : integer

The ID of the owning Notebook

deployment_id : integer

The ID for this deployment

Returns:

deployment_id : integer

The ID for this deployment.

user_id : integer

The ID of the owner.

host : string

Domain of the deployment.

name : string

Name of the deployment.

docker_image_name : string

The name of the docker image to pull from DockerHub.

docker_image_tag : string

The tag of the docker image to pull from DockerHub (default: latest).

display_url : string

URL that displays the deployed platform object and includes auth token.

memory : integer

The memory allocated to the deployment.

cpu : integer

The cpu allocated to the deployment.

state : string

The state of the deployment.

state_message : string

A detailed description of the state.

created_at : string/time

updated_at : string/time

published : boolean

notebook_id : integer

The ID of owning Notebook

list(*, hidden='DEFAULT', archived='DEFAULT', author='DEFAULT', status='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')

List Notebooks

Parameters:

hidden : boolean, optional

If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.

archived : string, optional

The archival status of the requested object(s).

author : string, optional

If specified, return imports from this author. It accepts a comma-separated list of author IDs.

status : string, optional

If specified, returns notebooks with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘pending’, ‘idle’.

limit : integer, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_num : integer, optional

Page number of the results to return. Defaults to the first page, 1.

order : string, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.

order_dir : string, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iterator : bool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for this notebook.

name : string

The name of this notebook.

language : string

The kernel language of this notebook.

description : string

The description of this notebook.

user : dict:

- id : integer
    The ID of this user.
- name : string
    This user's name.
- username : string
    This user's username.
- initials : string
    This user's initials.
- online : boolean
    Whether this user is online.

created_at : string/time

updated_at : string/time

most_recent_deployment : dict:

- deployment_id : integer
    The ID for this deployment.
- user_id : integer
    The ID of the owner.
- host : string
    Domain of the deployment.
- name : string
    Name of the deployment.
- docker_image_name : string
    The name of the docker image to pull from DockerHub.
- docker_im