Pactas API

Get your facts first, then you can distort them as you please Mark Twain

This document describes the resources of the pactas API. Please direct any inquiries to support@pactas.com

The API aims to be RESTful and to follow github's excellent API v3 very closely.

For improved readability, quotation marks are omitted in the JSON samples.

Schema

The API can be accessed via HTTPS at itero.pactas.com. Data is sent and received as JSON. Most API endpoints are at https://itero.pactas.com/api/v1/, but note that the OAuth endpoint and some client-facing endpoints such as file download are not under api/v1/.

Timestamps are returned in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

Errors

  1. Sending invalid JSON will result in a 400 Bad Request response.
  2. Sending invalid fields will result in a 422 Unprocessable Entity response.

HTTP Verbs

We are trying to use HTTP verbs as appropriately as possible. Hence, we (will) support
GET
Retrieves the resource, nullipotent.
POST
Used to create resources (as long as their future location is determined by the server).
PUT
Used for replacing objects or collections. PUT is idempotent.
DELETE
Used to delete resources (items or collections), idempotent.
PATCH, HEAD
Not yet supported.

Authentication & Authorization

Access to API resources is granted through OAuth 2.0 tokens. The tokens are not self-validated and can be revoked by the user at any time. Since calls are stateless, the token must be given in every request, either in an HTTP Authentication header or as a parameter:
as an HTTP header
curl -H "Authorization: Bearer OAUTH-TOKEN" https://itero.pactas.com
as a parameter
curl https://itero.pactas.com/?access_token=OAUTH-TOKEN

Acquiring Access Tokens

Pactas supports the two two-legged OAuth grants at this time: The 'Resource Owner Password Credentials Grant' and the 'Client Credentials Grant'.
Client Credentials Grant NEW in v.1.0.1
A 'confidential' OAuth client is a client that is able to securely store its own credentials (typically a web application). Such clients have a client_id and a client_secret, which can be used to retrieve an access token directly. This is the recommended approach if you want to query the Pactas API in response to webhooks or otherwise connect your web-based application to Pactas, because it decouples your API from your own frontend login and it does not run in any kind of user context.
Resource Owner Password Credentials Grant
requires the user to present user name and password to you. That comes with the usual drawbacks of password-based authentication: You need to store the password securely and a password change will render your backend inoperable. However, this flow can be used from e.g. mobile applications, desktop applications and other frontends that can't store a client_secret securely. Such applications are called 'public' OAuth clients.

Acquiring access tokens via Client Credentials Grant

POST /oauth/token/
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

grant_type=client_credentials

Here, the Basic authorization consists of the client_id and client_secret. Please note that client_id MUST NOT be specified in the request body because it's already contained in the Basic authorization header. You can create OAuth clients in your account under Settings -> Pactas Apps -> My Apps. If you create a confidential client, it will have both a client_id and a client_secret which can be used to retrieve an access token in this way.

Acquiring access tokens via Resource Owner Password Credentials Grant

POST /oauth/token/
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=YOUR-USER-NAME&password=YOUR-PASSWORD&client_id=YOUR-CLIENT-ID

Please note that username is the e-mail address of a pactas user, password is the user's password and client_id is the id of your app which must be registered with pactas before use. Hence, the password grant_type requires the user to share his password with you (2-legged OAuth).

Notes on HTTP Basic Authorization

HTTP Basic Authorization headers are Base64-encoded strings of the scheme username:password. For example, a user john.doe@example.com with password foobar would use the following header:
john.doe@example.com:foobar                               | Concatenated username and password
am9obi5kb2VAZXhhbXBsZS5jb206Zm9vYmFy                      | Base64 encoded
Authorization: Basic am9obi5kb2VAZXhhbXBsZS5jb206Zm9vYmFy | HTTP Header
In the client credentials grant, this boils down to client_id:client_secret, e.g.:
// client_id:client_secret
51efffb9eb596a2c2cb17aee:9b9b8cfd45d32e5153e7deecfee7fc44
// base64 encoded:
NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0
// formatted as HTTP Authorization header
Authorization: Basic NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0

3-legged OAuth

Further grant_types, specifically those required in 3-legged OAuth (3LO) where the user doesn't have to share his credentials with 3rd parties are planned.

Hypermedia

We're still working on making hypermedia the engine of application state (HATEOAS). Future responses will contain *_url fields so API clients can evolve more easily upon API changes.

Pagination

Pagination can be performed using skip and take parameters. However, skip/take pagination has some disadvantages:
  1. These are not stable cursors: if new elements are added in the mean time, the second page will contain elements that were present on the first page before
  2. skip is limited to 1000 elements, because the operation is rather expensive
Alternatively, some resources provide cursor-based pagination, e.g.
https://itero.pactas.com/api/v1/contracts/?from=50f6b3d7eb596a1268f5651e
These cursors are stable and much faster than skips. We recommend you use the value given in the Link HTTP header:
 Link: <https://api.pactas.com/contacts/?skip=100&take=100>; rel="next"

Rate Limiting

Currently, we limit requests to 1,000 per hour per user. If you need a higher limit, please get in touch. Rate limits are transferred in the HTTP headers:
HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 484
Unauthenticated requests will also go through a security filter. Do not make unauthenticated requests aggressively, because you could quickly end up in an IP ban.

Conditional Requests

Most responses return Last-Modified and ETag headers. You can use the values of these headers to make subsequent requests to those resources using the If-Modified-Since and If-None-Match headers, respectively. If the resource has not changed, the server will return a 304 Not Modified. Conditional requests that don't need to retrieve data do not count against your rate limit, so we encourage you to use it whenever possible.

CORS / JSONP

We don't support Cross Origin Resource Sharing or JSONP yet. If you need to access the API from a web client directly and need CORS or JSONP because the Same Origin Policy troubles you, please drop us a line.

Resource Table

This table gives an overview of the resource endpoints and supported HTTP verbs

Resource / URL GET POST PUT PATCH DELETE
/Orders Create a new signup or upgrade order
/Orders/:OrderId/Commit Process and finalize an order
/Customers List all customers Create a new customer
/Customers/:CustomerId Retrieve a customer Updates an existing customer Delete a customer
/Customers/:CustomerId/Contracts Retrieve all contracts of the given customer
/Contracts Lists all contracts
/Contracts/:ContractId Retrieves a contract's details Updates the contract Deletes a contract*
/Contracts/:ContractId/Usage Retrieve all available usage information about this contract Add new metered usage information to this contract
/Contract/:ContractId/ComponentSubscriptions/ Retrieve all available subscriptions in contract Create a new component subscription for this contract
/Contract/:ContractId/SelfServiceToken/ Retrieve an access token for the customer of the given contract
/Invoices Lists all invoices
/Invoices/:InvoiceId Retrieves an invoice
/InvoiceDrafts Lists all invoice drafts
/InvoiceDrafts/:InvoiceDraftId Retrieves an invoice draft Sends an invoice draft and converts it to an invoice
/Webhooks/ Retrieves a list of all webhooks Creates a new webhook
/Webhooks/:WebhookId Delete a webhook
* We don't really delete the contract because we must keep all records. However, the contract will no longer be counted against your quota and won't be billed anymore.

POST /Orders/

Create a new signup or upgrade order. Please note, orders might have a limited lifetime

Signup Order

For simple signup implementation we recommend using IteroJS rather than API, unless you have strong reasons.

Sample Request for new customer
{
	Cart: 
	{
		PlanVariantId: 53d09b8679650612881d6145,
		ComponentSubscriptions: 
		[
			{
				ComponentId: 53d09b8679650612881d6146,
				Quantity: 2
			}
		]
	},
	Customer: 
	{
		CompanyName: ACME Inc.,
		FirstName: John,
		LastName: Doe,
		VatId: DE424324234,
		EmailAddress: john.doe@example.com,
		Address: 
		{
			AddressLine1: c/o Coworking Ltd.,
			Street: Zschopauer Straße,
			HouseNumber: 42,
			PostalCode: 10123,
			City: Berlin,
			Country: DE
		}
	}
}

Remove ComponentSubscriptions or pass empty array if no components are subscribed.

Sample Request for existing customer
{
	CustomerId: 53d09b8679650612881d614d,
	Cart: 
	{
		PlanVariantId: 53d09b8679650612881d6145,
		ComponentSubscriptions: 
		[
			{
				ComponentId: 53d09b8679650612881d6146,
				Quantity: 2
			}
		]
	}
}
Sample Response
201 Created
{
	Id: 53d09b8679650612881d614c,
	AllowWithoutPaymentData: True,
	ComponentSubscriptions: 
	[
		{
			PreventModification: False,
			VatPercentage: 19,
			TotalNet: 2,
			TotalVat: 0.38,
			ComponentId: 53d09b8679650612881d6146,
			Quantity: 2
		}
	],
	Total: 7,
	TotalVat: 1.33,
	IsTrial: False,
	CustomerId: 53d09b8679650612881d614d,
	ContractId: 53d09b8679650612881d613d
}

Upgrade Order

Sample Request
{
	ContractId: 53d09b8679650612881d613d,
	Cart: 
	{
		PlanVariantId: 53d09b8679650612881d6147,
		ComponentSubscriptions: 
		[
			{
				ComponentId: 53d09b8679650612881d6148,
				Quantity: 2
			}
		],
		MeteredUsages: 
		[
			{
				ComponentId: 53d09b8679650612881d614b,
				Quantity: 3,
				Memo: Memo text,
				Key: Some unique external key 12345,
				DueDate: 2014-07-23T05:37:10.2830881Z
			}
		],
		EndComponentSubscriptions: 
		[
			53d09b8679650612881d6149,
			53d09b8679650612881d614a
		]
	}
}

Remove ComponentSubscriptions, EndComponentSubscriptions, MeteredUsages or pass empty array if not used.

Sample Response
201 Created
{
	Id: 53d09b8679650612881d614e,
	AllowWithoutPaymentData: True,
	ComponentSubscriptions: 
	[
		{
			PreventModification: False,
			VatPercentage: 19,
			TotalNet: 2,
			TotalVat: 0.38,
			ComponentId: 53d09b8679650612881d6148,
			Quantity: 2
		}
	],
	Total: 7,
	TotalVat: 1.33,
	IsTrial: False,
	CustomerId: 53d09b8679650612881d614f,
	ContractId: 53d09b8679650612881d613d
}

POST /Orders/:OrderId/commit

Process and finalize signup or upgrade order.

Finalizing a signup order usually includes an interactive payment processed on client side by the customer. When using this API endpoint rather than IteroJS no customer interaction is is involved. For this reason the endpoint can only be used for payment on account or if no payment method is required. For interactive payment please use paySignupInteractive() instead.

Committing signup order without payment method must be activated in plan variant settings!

When finalizing an upgrade order payment is done asynchronously from the order process with the currently active payment method. In contrast to upgradePaySync() in IteroJS the order is finished successful independent from a successful payment. If you don't want this behaviour please use upgradePaySync()

Sample Request for signup without payment data and for upgrade
POST /Orders/53d09b8679650612881d614e/Commit/
{
	
}
Sample Request for payment on account
POST /Orders/53d09b8679650612881d614e/Commit/
{
	PaymentMethod: "BlackLabel:InvoicePayment"
}
Sample Response

The created or upgraded contract

200 Ok
{
	Id: 53d09b8679650612881d613e,
	LastBillingDate: 2013-01-15T07:12:54Z,
	NextBillingDate: 2013-02-15T07:12:54Z,
	PlanId: 53d09b8679650612881d613a,
	CustomerId: 53d09b8679650612881d6137,
	LifecycleStatus: Active,
	CustomerName: ACME Inc.,
	Phases: 
	[
		{
			Type: Normal,
			StartDate: 2013-01-15T07:12:54Z,
			PlanVariantId: 53d09b8679650612881d613c,
			PlanId: 53d09b8679650612881d613a
		}
	],
	Balance: 0,
	Currency: EUR,
	PlanGroupId: 53d09b8679650612881d6139,
	PaymentProvider: InvoicePayment,
	EscalationSuspended: False,
	RecurringPaymentsPaused: False,
	StartDate: 2013-01-15T07:12:54Z,
	BilledUntil: 2013-02-15T07:12:54Z,
	PlanVariantId: 53d09b8679650612881d613c,
	Notes: Just a bunch of notes!
}

GET /Customers/

Retrieve a list of all customers

[
	{
		Id: 53d09b8679650612881d6137,
		CreatedAt: 0001-01-01,
		ExternalCustomerId: salesforce-lead-4546-58989,
		CompanyName: ACME Inc.,
		FirstName: John,
		LastName: Doe,
		Language: en,
		VatId: DE424324234,
		EmailAddress: john.doe@example.com,
		DefaultBearerMedium: Email,
		Notes: These notes are for your eyes only,
		Tag: "{
			'clientId' :  '2323432',
			 'trackingSource' :  'adwords',
			 'keyword' :  'bacon explosion',
			 'explanation' :  'free-form text,
			 only visible to your API'
		}",
		Address: 
		{
			AddressLine1: c/o Coworking Ltd.,
			Street: Zschopauer Straße,
			HouseNumber: 42,
			PostalCode: 10123,
			City: Berlin,
			Country: DE
		},
		Locale: en
	}
]

POST /Customers/

Create a new customer

Sample Request
{
	ExternalCustomerId: salesforce-lead-4546-58989,
	CompanyName: ACME Inc.,
	FirstName: John,
	LastName: Doe,
	Language: en,
	VatId: DE424324234,
	EmailAddress: john.doe@example.com,
	DefaultBearerMedium: Email,
	Notes: These notes are for your eyes only,
	Tag: "{
		'clientId' :  '2323432',
		 'trackingSource' :  'adwords',
		 'keyword' :  'bacon explosion',
		 'explanation' :  'free-form text,
		 only visible to your API'
	}",
	Address: 
	{
		AddressLine1: c/o Coworking Ltd.,
		Street: Zschopauer Straße,
		HouseNumber: 42,
		PostalCode: 10123,
		City: Berlin,
		Country: DE
	},
	Locale: en
}

GET /Customers/:CustomerId

Retrieve a single contact

{
	Id: 53d09b8679650612881d6137,
	CreatedAt: 0001-01-01,
	ExternalCustomerId: salesforce-lead-4546-58989,
	CompanyName: ACME Inc.,
	FirstName: John,
	LastName: Doe,
	Language: en,
	VatId: DE424324234,
	EmailAddress: john.doe@example.com,
	DefaultBearerMedium: Email,
	Notes: These notes are for your eyes only,
	Tag: "{
		'clientId' :  '2323432',
		 'trackingSource' :  'adwords',
		 'keyword' :  'bacon explosion',
		 'explanation' :  'free-form text,
		 only visible to your API'
	}",
	Address: 
	{
		AddressLine1: c/o Coworking Ltd.,
		Street: Zschopauer Straße,
		HouseNumber: 42,
		PostalCode: 10123,
		City: Berlin,
		Country: DE
	},
	Locale: en
}

PUT /Customers/:CustomerId

Replaces a contact's data

Request
{
	ExternalCustomerId: salesforce-lead-4546-58989,
	CompanyName: ACME Inc.,
	FirstName: John,
	LastName: Doe,
	Language: en,
	VatId: DE424324234,
	EmailAddress: john.doe@example.com,
	DefaultBearerMedium: Email,
	Notes: These notes are for your eyes only,
	Tag: "{
		'clientId' :  '2323432',
		 'trackingSource' :  'adwords',
		 'keyword' :  'bacon explosion',
		 'explanation' :  'free-form text,
		 only visible to your API'
	}",
	Address: 
	{
		AddressLine1: c/o Coworking Ltd.,
		Street: Zschopauer Straße,
		HouseNumber: 42,
		PostalCode: 10123,
		City: Berlin,
		Country: DE
	},
	Locale: en
}

DELETE /Customers/:CustomerId

Deletes a customer

Response
204 No Content

GET /Customers/:CustomerId/Contracts

Retrieves a list of all contracts for the given customer

Sample Request
GET /Customers/53d09b8679650612881d6137/Contracts/
[
	{
		Id: 53d09b8679650612881d613d,
		LastBillingDate: 2013-01-15T07:12:54Z,
		NextBillingDate: 2013-02-15T07:12:54Z,
		PlanId: 53d09b8679650612881d613a,
		CustomerId: 53d09b8679650612881d6137,
		LifecycleStatus: Active,
		CustomerName: ACME Inc.,
		Phases: 
		[
			{
				Type: Trial,
				StartDate: 2013-01-15T07:12:54Z,
				PlanVariantId: 53d09b8679650612881d613c,
				PlanId: 53d09b8679650612881d613a
			},
			{
				Type: Normal,
				StartDate: 2013-01-28T17:48:01Z,
				PlanVariantId: 53d09b8679650612881d613c,
				PlanId: 53d09b8679650612881d613a
			}
		],
		Balance: 0,
		Currency: EUR,
		PlanGroupId: 53d09b8679650612881d6139,
		PaymentBearer: 
		{
			CardType: Visa,
			ExpiryMonth: 12,
			ExpiryYear: 2018,
			Holder: Jim Doe,
			Country: DE,
			Last4: 1852,
			Type: CreditCard
		},
		PaymentProvider: Stripe,
		EscalationSuspended: False,
		RecurringPaymentsPaused: False,
		StartDate: 2013-01-15T07:12:54Z,
		EndDate: 2015-01-15T07:12:54Z,
		BilledUntil: 2013-02-15T07:12:54Z,
		PlanVariantId: 53d09b8679650612881d613c,
		Notes: Just a bunch of notes!
	}
]

GET /Contracts

Retrieves a list of all contracts

Response
[
	{
		Id: 53d09b8679650612881d613d,
		LastBillingDate: 2013-01-15T07:12:54Z,
		NextBillingDate: 2013-02-15T07:12:54Z,
		PlanId: 53d09b8679650612881d613a,
		CustomerId: 53d09b8679650612881d6137,
		LifecycleStatus: Active,
		CustomerName: ACME Inc.,
		Phases: 
		[
			{
				Type: Trial,
				StartDate: 2013-01-15T07:12:54Z,
				PlanVariantId: 53d09b8679650612881d613c,
				PlanId: 53d09b8679650612881d613a
			},
			{
				Type: Normal,
				StartDate: 2013-01-28T17:48:01Z,
				PlanVariantId: 53d09b8679650612881d613c,
				PlanId: 53d09b8679650612881d613a
			}
		],
		Balance: 0,
		Currency: EUR,
		PlanGroupId: 53d09b8679650612881d6139,
		PaymentBearer: 
		{
			CardType: Visa,
			ExpiryMonth: 12,
			ExpiryYear: 2018,
			Holder: Jim Doe,
			Country: DE,
			Last4: 1852,
			Type: CreditCard
		},
		PaymentProvider: Stripe,
		EscalationSuspended: False,
		RecurringPaymentsPaused: False,
		StartDate: 2013-01-15T07:12:54Z,
		EndDate: 2015-01-15T07:12:54Z,
		BilledUntil: 2013-02-15T07:12:54Z,
		PlanVariantId: 53d09b8679650612881d613c,
		Notes: Just a bunch of notes!
	}
]

GET /Contracts/:ContractId

Retrieves a contract by id


Sample Request
GET /Contracts/53d09b8679650612881d613d

Response
{
	Id: 53d09b8679650612881d613d,
	LastBillingDate: 2013-01-15T07:12:54Z,
	NextBillingDate: 2013-02-15T07:12:54Z,
	PlanId: 53d09b8679650612881d613a,
	CustomerId: 53d09b8679650612881d6137,
	LifecycleStatus: Active,
	CustomerName: ACME Inc.,
	Phases: 
	[
		{
			Type: Trial,
			StartDate: 2013-01-15T07:12:54Z,
			PlanVariantId: 53d09b8679650612881d613c,
			PlanId: 53d09b8679650612881d613a
		},
		{
			Type: Normal,
			StartDate: 2013-01-28T17:48:01Z,
			PlanVariantId: 53d09b8679650612881d613c,
			PlanId: 53d09b8679650612881d613a
		}
	],
	Balance: 0,
	Currency: EUR,
	PlanGroupId: 53d09b8679650612881d6139,
	PaymentBearer: 
	{
		CardType: Visa,
		ExpiryMonth: 12,
		ExpiryYear: 2018,
		Holder: Jim Doe,
		Country: DE,
		Last4: 1852,
		Type: CreditCard
	},
	PaymentProvider: Stripe,
	EscalationSuspended: False,
	RecurringPaymentsPaused: False,
	StartDate: 2013-01-15T07:12:54Z,
	EndDate: 2015-01-15T07:12:54Z,
	BilledUntil: 2013-02-15T07:12:54Z,
	PlanVariantId: 53d09b8679650612881d613c,
	Notes: Just a bunch of notes!
}

PATCH /Contracts/:ContractId

Updates a contract in place

Sample Request
PATCH /Contracts/53d09b8679650612881d613d
Response
200 OK
{
	Id: 53d09b8679650612881d613d,
	LastBillingDate: 2013-01-15T07:12:54Z,
	NextBillingDate: 2013-02-15T07:12:54Z,
	PlanId: 53d09b8679650612881d613a,
	CustomerId: 53d09b8679650612881d6137,
	LifecycleStatus: Active,
	CustomerName: ACME Inc.,
	Phases: 
	[
		{
			Type: Trial,
			StartDate: 2013-01-15T07:12:54Z,
			PlanVariantId: 53d09b8679650612881d613c,
			PlanId: 53d09b8679650612881d613a
		},
		{
			Type: Normal,
			StartDate: 2013-01-28T17:48:01Z,
			PlanVariantId: 53d09b8679650612881d613c,
			PlanId: 53d09b8679650612881d613a
		}
	],
	Balance: 0,
	Currency: EUR,
	PlanGroupId: 53d09b8679650612881d6139,
	PaymentBearer: 
	{
		CardType: Visa,
		ExpiryMonth: 12,
		ExpiryYear: 2018,
		Holder: Jim Doe,
		Country: DE,
		Last4: 1852,
		Type: CreditCard
	},
	PaymentProvider: Stripe,
	EscalationSuspended: False,
	RecurringPaymentsPaused: False,
	StartDate: 2013-01-15T07:12:54Z,
	EndDate: 2015-01-15T07:12:54Z,
	BilledUntil: 2013-02-15T07:12:54Z,
	PlanVariantId: 53d09b8679650612881d613c,
	Notes: Just a bunch of notes!
}

DELETE /Contracts/:ContractId

Deletes a contract

Sample Request
DELETE /Contracts/53d09b8679650612881d613d
Response
204 No Content

GET /Contracts/:ContractId/Usage

Retrieves a contract's associated usage


Sample Request
GET /Contracts/53d09b8679650612881d613d/Usage

Response
{
	Id: 53d09b8679650612881d6140,
	ContractId: 53d09b8679650612881d613d,
	TransferredAt: 2013-02-04T11:02:11Z,
	BilledOn: 2013-02-15T07:12:54Z,
	ComponentId: 53d09b8679650612881d613b,
	Quantity: 124,
	Memo: Foo Usage,
	DueDate: 2013-01-30T01:03:31Z
}

POST /Contracts/:ContractId/Usage

Posts new metered usage data (e.g. amount of data transferred, number of kilowatts used, etc.)


Sample Request
POST /Contracts/53d09b8679650612881d613d/Usage
{
	ComponentId: 53d09b8679650612881d613b,
	Quantity: 124,
	Memo: Foo Usage,
	DueDate: 2013-01-30T01:03:31Z
}
ComponentId
The id of the component. The referenced component must be a metered usage component.
Amount
The number of items used
Memo
A string that will be displayed alongside the component's description in the invoice. For instance, this might contain the name of an ad campaign or the name of an affiliate site.
DueDate
Metered usage data must always be attributed to a single point in time, which is given by DueDate

Response
201 Created
{
	Id: 53d09b8679650612881d6140,
	ContractId: 53d09b8679650612881d613d,
	TransferredAt: 2013-02-04T11:02:11Z,
	BilledOn: 2013-02-15T07:12:54Z,
	ComponentId: 53d09b8679650612881d613b,
	Quantity: 124,
	Memo: Foo Usage,
	DueDate: 2013-01-30T01:03:31Z
}
TransferredAt
The date and time the usage was transmitted to pactas.
BilledOn
The date and time this usage was billed by Pactas. If this field is null, the usage hasn't been billed yet and can still be deleted.

GET /Contracts/:ContractId/ComponentSubscriptions

Retrieves current subscriptions in the selected contract


Sample Request
GET /Contracts/53d09b8679650612881d613d/ComponentSubscriptions

Response
{
	Id: 53d09b8679650612881d6141,
	ContractId: 53d09b8679650612881d613d,
	CustomerId: 53d09b8679650612881d6137,
	BilledUntil: 2012-02-22T01:43:20Z,
	ComponentId: 53d09b8679650612881d613f,
	Quantity: 4,
	StartDate: 2012-01-03,
	Memo: FooBar
}

POST /Contracts/:ContractId/ComponentSubscriptions

Create a new component subscription for this contract, e.g. a new website or user to be billed continuously.


Sample Request
POST /Contracts/53d09b8679650612881d613d/ComponentSubscriptions
{
	ComponentId: 53d09b8679650612881d613f,
	Quantity: 4,
	StartDate: 2012-01-03,
	Memo: FooBar
}

Response
201 Created
{
	Id: 53d09b8679650612881d6141,
	ContractId: 53d09b8679650612881d613d,
	CustomerId: 53d09b8679650612881d6137,
	BilledUntil: 2012-02-22T01:43:20Z,
	ComponentId: 53d09b8679650612881d613f,
	Quantity: 4,
	StartDate: 2012-01-03,
	Memo: FooBar
}

GET /Contracts/:ContractId/SelfServiceToken

Retrieve a short-lived access token that can be used by your customers to change their account and payment information for the given contract. Since the token is short-lived, it should not be used with e.g. email notifications. Retrieve the token immediately before redirecting the customer.


Sample Request
GET /Contracts/53d09b8679650612881d613d/SelfServiceToken

Response
200 OK
{
	Expiry: 2014-07-25T05:37:10.2830881Z,
	Token: 522703b9eb596a0f40480825$1378374980$JDBWIYOmg34kr_mFIUFP,
	Purpose: CustomerPortal,
	Url: "https://itero.pactas.com/portal/data/522703b9eb596a0f40480825$1378374980$JDBWIYOmg34kr_mFIUFP/"
}

GET /Invoices

Retrieves a list of all invoices


Request
GET /Invoices

Response
[
	{
		Id: 53d09b8679650612881d6143,
		InvoiceNumber: SAN//2012//07--2434,
		CustomerId: 53d09b8679650612881d6137,
		SentAt: 2012-07-03T23:02:22Z,
		DueDate: 2012-08-02,
		RecipientName: OldTek GmbH,
		RecipientSubName: Hermann Anton Müller,
		RecipientAddress: 
		{
			AddressLine1: c/o Andreas Meister,
			Street: Sternstraße,
			HouseNumber: 43,
			PostalCode: 80538,
			City: München,
			Country: DE
		},
		Currency: EUR,
		TotalNet: 211.60,
		TotalVat: 40.20,
		TotalGross: 251.80,
		IsInvoice: False
	}
]

GET /Invoices/:InvoiceId

Retrieves a document's details

Response
{
	SenderName: ACME UG (haftungsbeschränkt),
	SenderAddress: 
	{
		AddressLine1: c/o Dr. Ricco Deutscher,
		Street: Fichardstraße,
		HouseNumber: 18a,
		PostalCode: 60322,
		City: Frankfurt am Main,
		Country: DE
	},
	SenderVatId: DE57567543,
	SenderTaxNumber: 234/4234/54543,
	RecipientVatId: DE4564587981,
	RecipientTaxNumber: ,
	ItemList: 
	[
		{
			ProductNumber: P.IT-S,
			Description: Pactas.Itero Account,
			Quantity: 1,
			PricePerUnit: 199,
			VatPercentage: 19,
			TotalNet: 0,
			TotalVat: 0,
			TotalGross: 0
		},
		{
			ProductNumber: SnailMail.DE,
			Description: Snail Mail Invoices,
			Quantity: 14,
			PricePerUnit: 0.90,
			VatPercentage: 19,
			TotalNet: 0,
			TotalVat: 0,
			TotalGross: 0
		}
	],
	Prologue: "Dear Sirs,
	
thank you for your order. Please find the invoice attached",
	Epilogue: Thank you for choosing Pactas,
	DeliveryPeriodStart: 2012-01-12T03:05:12Z,
	DeliveryPeriodEnd: 2012-02-12T03:05:12Z,
	VatDescriptors: 
	[
		{
			VatPercentage: 19,
			TotalNet: 211.60,
			TotalVat: 40.20,
			TotalGross: 251.80
		}
	],
	BearerMedium: Email,
	ReverseCharge: False,
	Id: 53d09b8679650612881d6143,
	InvoiceNumber: SAN//2012//07--2434,
	CustomerId: 53d09b8679650612881d6137,
	SentAt: 2012-07-03T23:02:22Z,
	DueDate: 2012-08-02,
	RecipientName: OldTek GmbH,
	RecipientSubName: Hermann Anton Müller,
	RecipientAddress: 
	{
		AddressLine1: c/o Andreas Meister,
		Street: Sternstraße,
		HouseNumber: 43,
		PostalCode: 80538,
		City: München,
		Country: DE
	},
	Currency: EUR,
	TotalNet: 211.60,
	TotalVat: 40.20,
	TotalGross: 251.80,
	IsInvoice: False
}

POST /Invoices/:InvoiceId/downloadLink

Creates a file download token for the given invoice. The file can subsequenlty be downloaded through the given URL. Please note that that URL is not under /api/v1 and doesn't need an OAuth token, i.e. you can present these links to your users. Consequently, the links have limited validity.

Response
{
	Url: /Files/1vRmbVt13TyAqfLwXGXjxb,
	Expiry: 2014-07-25T05:37:10.2830881Z
}

GET /InvoiceDrafts

Retrieves a list of all invoice drafts


Request
GET /InvoiceDrafts

Response
[
	{
		Id: 53d09b8679650612881d6142,
		RecipientName: OldTek GmbH,
		RecipientSubName: Hermann Anton Müller,
		Created: 0001-01-01,
		Currency: EUR,
		TotalGross: 251.80,
		TotalNet: 211.60,
		TotalVat: 40.20,
		CustomerId: 53d09b8679650612881d6137,
		ContractId: 53d09b8679650612881d613d,
		ExternalCustomerId: salesforce-lead-4546-58989,
		IsInvoice: False
	}
]

GET /InvoiceDrafts/:InvoiceDraftId

Retrieves a draft


Request
GET /InvoiceDrafts/:InvoiceDraftId

Response
{
	RecipientAddress: 
	{
		AddressLine1: c/o Andreas Meister,
		Street: Sternstraße,
		HouseNumber: 43,
		PostalCode: 80538,
		City: München,
		Country: DE
	},
	RecipientVatId: DE4564587981,
	Language: en,
	ReverseCharge: False,
	DeliveryPeriodStart: 2012-01-12T03:05:12Z,
	DeliveryPeriodEnd: 2012-02-12T03:05:12Z,
	SequenceId: a7f7,
	Prologue: "Dear Sirs,
	
thank you for your order. Please find the invoice attached",
	Epilogue: Thank you for choosing Pactas,
	ItemList: 
	[
		{
			ProductNumber: P.IT-S,
			Description: Pactas.Itero Account,
			Quantity: 1,
			PricePerUnit: 199,
			VatPercentage: 19,
			TotalNet: 0,
			TotalVat: 0,
			TotalGross: 0
		},
		{
			ProductNumber: SnailMail.DE,
			Description: Snail Mail Invoices,
			Quantity: 14,
			PricePerUnit: 0.90,
			VatPercentage: 19,
			TotalNet: 0,
			TotalVat: 0,
			TotalGross: 0
		}
	],
	VatDescriptors: 
	[
		{
			VatPercentage: 19,
			TotalNet: 211.60,
			TotalVat: 40.20,
			TotalGross: 251.80
		}
	],
	Id: 53d09b8679650612881d6142,
	RecipientName: OldTek GmbH,
	RecipientSubName: Hermann Anton Müller,
	Created: 0001-01-01,
	Currency: EUR,
	TotalGross: 251.80,
	TotalNet: 211.60,
	TotalVat: 40.20,
	CustomerId: 53d09b8679650612881d6137,
	ContractId: 53d09b8679650612881d613d,
	ExternalCustomerId: salesforce-lead-4546-58989,
	IsInvoice: False
}

POST /InvoiceDrafts/:InvoiceDraftId

Sends the given invoice draft id, thus converting it to an invoice. Returns the newly created invoice.


Request
POST /InvoiceDrafts/:InvoiceDraftId

Response (equivalent to GET /Invoices/:InvoiceId)

GET /Files

Retrieves a list of all files

Response
[
	{
		Id: ca30311db46e47ad87af3dd324148c67,
		Name: 58ff267f0c0349f5b866897902fc7aa9,
		MD5: cd85145ea39819e20e723170594ca7ca,
		Length: 87124,
		UploadDate: 2012-11-11T10:11:00Z,
		ContentType: application/pdf
	}
]

GET /Files/:FileId

Retrieves a file immediately

Heads up! In the future, this will return a 302 redirect instead of returning the data immediately.
Response
(binary)

GET /PlanGroups

Sample Request
GET /PlanGroups
Sample Respose
[
	{
		Id: 53d09b8679650612881d6139,
		Name: 
		{
			_c: Pactas Itero
		},
		Description: Pactas.Itero Billing System,
		Currency: EUR,
		TaxPolicyId: 53d09b8679650612881d6138,
		SelfServiceSettings: 
		{
			ShowVatId: True,
			ShowCompanyName: True,
			ShowEmailAddress: False,
			ShowBillingAddress: False
		}
	}
]

GET /Plans

Sample Request
GET /Plans
Sample Respose
[
	{
		PlanGroupId: 53d09b8679650612881d6139,
		Id: 53d09b8679650612881d613a,
		Name: 
		{
			_c: Pactas Itero L
		},
		TrialPeriod: 
		{
			Unit: Day,
			Quantity: 14
		},
		TrialEndPolicy: DeactivateAccount
	}
]

GET /PlanVariants

Sample Request
GET /PlanVariants
Sample Respose
[
	{
		Id: 53d09b8679650612881d613c,
		PlanId: 53d09b8679650612881d613a,
		AllowSelfService: True,
		AllowWithoutPaymentData: False,
		ContractPeriod: 
		{
			Unit: Month,
			Quantity: 1
		},
		BillingPeriod: 
		{
			Unit: Month,
			Quantity: 1
		},
		FeePeriod: 
		{
			Unit: Month,
			Quantity: 1
		},
		PaymentPeriodMode: PrePaid,
		Quota: 
		[
			{
				ComponentId: 53d09b8679650612881d613b,
				ComponentName: Snail Mail Invoice Delivery,
				Quota: 5
			}
		],
		RecurringFee: 199,
		SetupFee: 0
	}
]

Webhooks

Pactas allows you to subscribe to a number of webhooks. This section describes how to register, list and de-register webhooks. For details on the webhooks themselves, please refer to the webhooks documentation.

GET /webhooks

Lists all webhooks that you currently have registered

Sample Request
GET /webhooks
Sample Respose
[
	{
		Id: 53d09b8679650612881d6144,
		Url: "http://example.com/pactas-hooks/account-hook",
		Events: 
		[
			AccountCreated,
			ContractChanged,
			PaymentSucceeded,
			PaymentFailed,
			DebitAuthCancelled,
			CustomerChanged
		]
	}
]

POST /webhooks

Registers a new webhook for the given events. Note that you can have multiple webhooks subscribed to the same event. This way, you can makes it easier to hook third parties in your account.

Sample Request
POST /webhooks
{
	Url: "http://example.com/pactas-hooks/account-hook",
	Events: 
	[
		AccountCreated,
		ContractChanged,
		PaymentSucceeded,
		PaymentFailed,
		DebitAuthCancelled,
		CustomerChanged
	]
}
Sample Respose
201 Created
{
	Id: 53d09b8679650612881d6144,
	Url: "http://example.com/pactas-hooks/account-hook",
	Events: 
	[
		AccountCreated,
		ContractChanged,
		PaymentSucceeded,
		PaymentFailed,
		DebitAuthCancelled,
		CustomerChanged
	]
}

DELETE /webhooks/:webhookId

Deletes the webhook from the system. Note that this will NOT stop retrying of webhooks that are already queued up!

Sample Request
DELETE /webhooks/:webhookId
Sample Respose
204 No Content