Beanstalk

Integration Resource

Admin privileges required for these API methods.

Integration is a resource that belongs to a Repository and contains information about an external service with which the repository should communicate during pushes and commits.

For the list of supported external services, check available integration types list below.

Readable attributes

id integer Unique ID of the Integration.
account_id integer ID of the associated Account.
repository_id integer ID of the associated Repository.
type string Type of the integration. See list of available types below.
active boolean Indicates if the integration is active or note.
updated_at datetime Time when the integration was last updated.
created_at datetime Time when the integration was first added to the system.
deactivated_at datetime Time when the integration was deactivated.
activated_at datetime Time when the integration was activated.
activated_by_user_id integer ID of the User who activated the integration last.
deactivated_by_user_id integer ID of the User who deactivated the integration last.

Every integration type has it’s own unique read-only attributes in addition to these.

Writable attributes

type string Required on create. Must be unique per Account.

Every integration type has it’s own unique writable attributes in addition to this one.

Available integration types

Some integrations are currently accessible in read-only mode.

Note on attributes

Every integration type has it’s own unique set of attributes in addition to those described above.

Some of the attributes below are write-only (such as passwords and API tokens). This means that you can send them to Beanstalk, but you can never retrieve them back. This is a security precaution.

Some attributes require a YAML-serialized hash. Here’s an example of such hash:

yaml
--- 
18: 642524
2: 84132933
9: 2292663

BasecampIntegration unique attributes

This integration is for Basecamp Classic only. BasecampNext is for new Basecamp.

service_url integer Full URL of a Basecamp account. With protocol.
service_project_id integer ID of a Basecamp project with which Beanstalk should communicate.
service_project_name string Name of the Basecamp project (will be detected automatically).
service_company_name string Name of the Basecamp company (will be detected automatically).
service_access_token string Basecamp API token (write-only).
service_time_tracking boolean Use Basecamp time tracking feature.
service_messaging boolean Post message to Basecamp on every commit/push.
service_message_private boolean Post private messages to Basecamp.
service_message_category integer Basecamp Message Category ID that should be used for messages created by Beanstalk.
service_user_assignments string Hash of Beanstalk User IDs with associated Basecamp User IDs. Beanstalk is using this hash when posting time entries to Basecamp to determine for which user it should create a time entry on Basecamp. (serialized YAML).

BasecampNextIntegration unique attributes

This integration is for new Basecamp only. BasecampIntegration is for Basecamp Classic.

service_access_token string 37Signals Launchpad OAuth2 secret token (write-only).
service_url integer Full URL of a Basecamp account. With protocol.
service_project_id integer ID of a Basecamp project with which Beanstalk should communicate.
service_project_name string Name of the Basecamp project.

CampfireIntegration unique attributes

service_domain string Sub-domain of a Campfire installation. Without protocol or domain.
service_access_token string Campfire API token (write-only).
service_room_name string Name of the room to which you want Beanstalk to post notifications.
listen_commits boolean Notify about commits/pushes.
listen_deployments boolean Notify about deployments.

HipchatIntegration unique attributes

service_access_token string Hipchat Admin API token.
service_room_name string Name of the room to which you want Beanstalk to post notifications.
listen_commits boolean Notify about commits/pushes.
listen_deployments boolean Notify about deployments.

FogBugzIntegration unique attributes

service_url string Full URL of a FogBugz installation. With protocol.
service_login string FogBugz login or email (write-only).
service_password string FogBugz password (write-only).

FreckleIntegration unique attributes

service_url string Full URL of a freckle installation. With protocol.
service_access_token string Freckle API token (write-only).
service_project_id integer ID of a freckle Project to which Beanstalk should post time entries.
service_project_name string Name of the freckle Project (will be detected automatically).

HarvestIntegration unique attributes

service_url string Full URL of a Harvest installation. With protocol.
service_login string Harvest email (write-only).
service_password string Harvest password (write-only).
service_project_id integer ID of a Harvest Project to which Beanstalk should post time entries.
service_project_name string Name of the Harvest project (will be detected automatically).
service_company_name string Name of a Harvest Company (will be detected automatically).

LighthouseIntegration unique attributes

service_domain string Sub-domain of a Lighthouse installation. Without protocol or domain.
service_access_token string Lighthouse API token (write-only).
service_project_id integer Harvest Project ID to which Beanstalk should post time entries.
service_project_name string Name of the Harvest project (will be detected automatically).
service_user_assignments string Hash of Beanstalk User IDs with associated Harvest Task IDs. Beanstalk can post time entries with different Harvest Tasks for every user. This is an optional parameter (serialized YAML, write-only).

SifterIntegration unique attributes

service_domain string Sub-domain of a Sifter installation. Without protocol or domain.
service_access_token string Sifter Access Key (write-only).
service_project_url string Full URL of a Sifter project with which Beanstalk should communicate. Example: https://sub-domain.sifterapp.com/api/projects/873463
service_project_name string Name of the Sifter project.

WebHooksIntegration unique attributes

service_url string URL of the web hook.

ModularWebHooksIntegration unique attributes

name string Name of the webhook.
service_url string URL of the webhook.
triggers object Flags describing when to trigger the webhook.
triggers/commit boolean On each commit (Subversion only).
triggers/push boolean On each push (Git only).
triggers/deploy boolean Every time a deployment is finished.
triggers/comment boolean Any comment is posted on a changeset, a file or a code review.
triggers/create_branch boolean When a branch is created.
triggers/delete_branch boolean When a branch is deleted.
triggers/create_tag boolean When a tag is created.
triggers/delete_tag boolean When a tag is deleted.

ZendeskIntegration unique attributes

service_domain string Sub-domain of a Zendesk installation. Without protocol or domain.
service_login string Zendesk email (write-only).
service_password string Zendesk password (write-only).
service_user_assignments string Hash of Beanstalk User IDs with associated Zendesk User IDs. Beanstalk will associate created Zendesk messages with users in your Beanstalk account (serialized YAML).

JiraIntegration unique attributes

service_url string The URL of your JIRA installation. With Protocol.
service_login string JIRA username (write-only).
service_password string JIRA password (write-only).
service_project_name string JIRA project key.

DoneDoneIntegration unique attributes

service_domain string DoneDone account subdomain.
service_login string DoneDone username.
service_password string DoneDone password or API token (write-only).
service_project_id integer DoneDone project ID.

SlackIntegration unique attributes

service_room_name string Slack channel name (with #) or private group name.

Find All Integrations

json http-request 
GET /api/repositories/{REPOSITORY_ID}/integrations.json

Click to expand…

json http-response 
STATUS: 200

[{
  "integration": {
    "created_at": "2012/03/21 16:17:14 -0700",
    "activated_at": "2012/03/21 16:18:13 -0700",
    "service_message_category": "406863",
    "updated_at": "2012/03/21 16:18:13 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "service_message_private": false,
    "id": 19,
    "type": "BasecampIntegration",
    "service_url": "https://example.basecamphq.com",
    "service_time_tracking": false,
    "repository_id": 34,
    "service_user_assignments": {
      "2": 2713393
    },
    "service_messaging": true,
    "active": true
  }
}]
xml http-request 
GET /api/repositories/{REPOSITORY_ID}/integrations.xml

Click to expand…

xml http-response 
STATUS: 200

<?xml version="1.0" encoding="UTF-8"?>
<integrations type="array">
  <integration>
    <account-id type="integer">2</account-id>
    <activated-at type="datetime">2012-03-21T16:18:13-07:00</activated-at>
    <activated-by-user-id type="integer">2</activated-by-user-id>
    <active type="boolean">true</active>
    <created-at type="datetime">2012-03-21T16:17:14-07:00</created-at>
    <deactivated-at type="datetime" nil="true"/>
    <deactivated-by-user-id type="integer" nil="true"/>
    <id type="integer">19</id>
    <repository-id type="integer">34</repository-id>
    <service-message-category>765433</service-message-category>
    <service-message-private type="boolean">false</service-message-private>
    <service-messaging type="boolean">true</service-messaging>
    <service-time-tracking type="boolean">false</service-time-tracking>
    <service-url>https://example.basecamphq.com</service-url>
    <service-user-assignments type="yaml">
      --- 2: 65432
    </service-user-assignments>
    <type>BasecampIntegration</type>
    <updated-at type="datetime">2012-03-21T16:18:13-07:00</updated-at>
  </integration>

  <integration>
    <account-id type="integer">2</account-id>
    <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
    <activated-by-user-id type="integer">2</activated-by-user-id>
    <active type="boolean">true</active>
    <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
    <deactivated-at type="datetime" nil="true"/>
    <deactivated-by-user-id type="integer" nil="true"/>
    <id type="integer">20</id>
    <repository-id type="integer">34</repository-id>
    <service-url>http://www.postbin.org/18dvegk</service-url>
    <type>WebHooksIntegration</type>
    <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
  </integration>
</integrations>

Find Integration

json http-request 
GET /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}.json

Click to expand…

json http-response 
STATUS: 200

{
  "integration": {
    "created_at": "2012/03/21 16:17:14 -0700",
    "activated_at": "2012/03/21 16:18:13 -0700",
    "service_message_category": "406863",
    "updated_at": "2012/03/21 16:18:13 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "service_message_private": false,
    "id": 19,
    "type": "BasecampIntegration",
    "service_url": "https://example.basecamphq.com",
    "service_time_tracking": false,
    "repository_id": 34,
    "service_user_assignments": {
      "2": 2713393
    },
    "service_messaging": true,
    "active": true
  }
}
xml http-request 
GET /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}.xml

Click to expand…

xml http-response 
STATUS: 200

<?xml version="1.0" encoding="UTF-8"?>
<integration>
  <account-id type="integer">2</account-id>
  <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
  <activated-by-user-id type="integer">2</activated-by-user-id>
  <active type="boolean">true</active>
  <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
  <deactivated-at type="datetime" nil="true"/>
  <deactivated-by-user-id type="integer" nil="true"/>
  <id type="integer">20</id>
  <repository-id type="integer">34</repository-id>
  <service-url>http://www.postbin.org/18dvegk</service-url>
  <type>WebHooksIntegration</type>
  <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
</integration>

Create Integration

New integrations are activated automatically. Connectivity with the integrating service will be checked during this request.

json http-request 
POST /api/repositories/{REPOSITORY_ID}/integrations.json

{
  "integration": {
    "type": "WebHooksIntegration",
    "service_url": "http://www.postbin.org/13leoic"
  }
}

Click to expand…

json http-response 
STATUS: 201

{
  "integration": {
    "created_at": "2012/03/21 16:27:52 -0700",
    "activated_at": "2012/03/21 16:27:53 -0700",
    "updated_at": "2012/03/21 16:27:53 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "id": 20,
    "type": "WebHooksIntegration",
    "service_url": "http://www.postbin.org/13leoic",
    "repository_id": 34,
    "active": true
  }
}
xml http-request 
POST /api/repositories/{REPOSITORY_ID}/integrations.xml

<integration>
  <type>WebHooksIntegration</type>
  <service-url>http://www.postbin.org/18dvegk</service-url>
</integration>

Click to expand…

xml http-response 
STATUS: 201

<?xml version="1.0" encoding="UTF-8"?>
<integration>
  <account-id type="integer">2</account-id>
  <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
  <activated-by-user-id type="integer">2</activated-by-user-id>
  <active type="boolean">true</active>
  <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
  <deactivated-at type="datetime" nil="true"/>
  <deactivated-by-user-id type="integer" nil="true"/>
  <id type="integer">20</id>
  <repository-id type="integer">34</repository-id>
  <service-url>http://www.postbin.org/18dvegk</service-url>
  <type>WebHooksIntegration</type>
  <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
</integration>

Update Integration

json http-request 
PUT /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}.json

{
  "integration": {
    "service_url": "http://example.com?webhook"
  }
}

Click to expand…

json http-response 
STATUS: 200

{
  "integration": {
    "created_at": "2012/03/21 16:27:52 -0700",
    "activated_at": "2012/03/21 16:27:53 -0700",
    "updated_at": "2012/03/21 16:27:53 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "id": 20,
    "type": "WebHooksIntegration",
    "service_url": "http://example.com?webhook",
    "repository_id": 34,
    "active": true
  }
}

--OR IF INVALID--

{
  "errors": ["service url is invalid"]
}
xml http-request 
PUT /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}.xml

<integration>
  <service-url>http://example.com?webhook</service-url>
</integration>

Click to expand…

xml http-response 
STATUS: 200

<?xml version="1.0" encoding="UTF-8"?>
<integration>
  <account-id type="integer">2</account-id>
  <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
  <activated-by-user-id type="integer">2</activated-by-user-id>
  <active type="boolean">true</active>
  <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
  <deactivated-at type="datetime" nil="true"/>
  <deactivated-by-user-id type="integer" nil="true"/>
  <id type="integer">20</id>
  <repository-id type="integer">34</repository-id>
  <service-url>http://example.com?webhook</service-url>
  <type>WebHooksIntegration</type>
  <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
</integration>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Service url can't be blank</error>
</errors>

Activate Integration

json http-request 
PUT /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}/activate.json

Click to expand…

json http-response 
STATUS: 200

{
  "integration": {
    "created_at": "2012/03/21 16:27:52 -0700",
    "activated_at": "2012/03/21 16:27:53 -0700",
    "updated_at": "2012/03/21 16:27:53 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "id": 20,
    "type": "WebHooksIntegration",
    "service_url": "http://www.postbin.org/13leoic",
    "repository_id": 34,
    "active": true
  }
}
xml http-request 
PUT /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}/activate.xml

Click to expand…

xml http-response 
STATUS: 200

<?xml version="1.0" encoding="UTF-8"?>
<integration>
  <account-id type="integer">2</account-id>
  <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
  <activated-by-user-id type="integer">2</activated-by-user-id>
  <active type="boolean">true</active>
  <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
  <deactivated-at type="datetime" nil="true"/>
  <deactivated-by-user-id type="integer" nil="true"/>
  <id type="integer">20</id>
  <repository-id type="integer">34</repository-id>
  <service-url>http://example.com?webhook</service-url>
  <type>WebHooksIntegration</type>
  <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
</integration>

Deactivate Integration

json http-request 
PUT /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}/deactivate.json

Click to expand…

json http-response 
STATUS: 200

{
  "integration": {
    "created_at": "2012/03/21 16:27:52 -0700",
    "activated_at": "2012/03/21 16:27:53 -0700",
    "updated_at": "2012/03/21 16:27:53 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "id": 20,
    "type": "WebHooksIntegration",
    "service_url": "http://www.postbin.org/13leoic",
    "repository_id": 34,
    "active": false
  }
}
xml http-request 
PUT /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}/deactivate.xml

Click to expand…

xml http-response 
STATUS: 200

<?xml version="1.0" encoding="UTF-8"?>
<integration>
  <account-id type="integer">2</account-id>
  <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
  <activated-by-user-id type="integer">2</activated-by-user-id>
  <active type="boolean">false</active>
  <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
  <deactivated-at type="datetime" nil="true"/>
  <deactivated-by-user-id type="integer" nil="true"/>
  <id type="integer">20</id>
  <repository-id type="integer">34</repository-id>
  <service-url>http://example.com?webhook</service-url>
  <type>WebHooksIntegration</type>
  <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
</integration>

Delete Integration

This action permanently deletes information about the integration from the system. If you want to temporarily disable the integration use Deactivate action instead.

json http-request 
DELETE /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}.json

Click to expand…

json http-response 
STATUS: 200

{
  "integration": {
    "created_at": "2012/03/21 16:27:52 -0700",
    "activated_at": "2012/03/21 16:27:53 -0700",
    "updated_at": "2012/03/21 16:27:53 -0700",
    "activated_by_user_id": 2,
    "deactivated_by_user_id": null,
    "deactivated_at": null,
    "account_id": 2,
    "id": 20,
    "type": "WebHooksIntegration",
    "service_url": "http://www.postbin.org/13leoic",
    "repository_id": 34,
    "active": false
  }
}
xml http-request 
DELETE /api/repositories/{REPOSITORY_ID}/integrations/{INTGR_ID}.xml

Click to expand…

xml http-response 
STATUS: 200

<?xml version="1.0" encoding="UTF-8"?>
<integration>
  <account-id type="integer">2</account-id>
  <activated-at type="datetime">2012-03-21T16:27:53-07:00</activated-at>
  <activated-by-user-id type="integer">2</activated-by-user-id>
  <active type="boolean">false</active>
  <created-at type="datetime">2012-03-21T16:27:52-07:00</created-at>
  <deactivated-at type="datetime" nil="true"/>
  <deactivated-by-user-id type="integer" nil="true"/>
  <id type="integer">20</id>
  <repository-id type="integer">34</repository-id>
  <service-url>http://example.com?webhook</service-url>
  <type>WebHooksIntegration</type>
  <updated-at type="datetime">2012-03-21T16:27:53-07:00</updated-at>
</integration>