---
title: Subscriber API
slug: subscriber-api
docTags: 
createdAt: 2024-04-01T18:56:55.743Z
---

API for our integration partners who want to push subscribers into Jobylon.


In Jobylon, every Subscriber is represented by an email and an entity that can be of type Company or Group.

## Workflow

Subscriber API is an extension of the [Push API](docId:_IO2-SJeUjv6VGTRTGYoZ). To push a Subscriber, the partner must register with Jobylon to get the credentials to use the Push API.

### Create or Update

**POST** `/subscribe/`

**Payload**

Described in [Request Payload](docId\:bqYn-qUvPU9UwugPhL65G)

**Query String Parameters**

None

**Response**

Described in [Request Payload](docId\:bqYn-qUvPU9UwugPhL65G)

**Response Status**

| Status | Description                       |
| ------ | --------------------------------- |
| 200    | An existing subscriber was update |
| 200    | Subscriber created                |

:::hint{type="info"}
A subscriber is identified by the combination of its of `email`, `entity` and `entity_id`. 
:::

### Example

```shell
export HOST='https://staging.jobylon.com'
export API_VERSION='p1'
export APP_ID='0123456789123456'
export APP_KEY='AbC123XyZ'
```

```shell
# Request
curl -i \
    -X POST "$HOST/$API_VERSION/subscribe/" \
    -H "X-App-Id: $APP_ID" \
    -H "X-App-Key: $APP_KEY" \
    -H "Content-Type: application/json" \
    -d '{
	    "first_name": "Bruce",
	    "last_name": "Wayne",
	    "email":"bruce@waynecorp.com",
	    "filters": {
		    "categories": [578, 23],
		    "companies": [45, 87, 96, 97],
		    "departments": [13, 524, 6309],
		    "functions": [882, 4044],
		    "locations": ["Gotham, Gothenburg"],
		    "location_area_1": ["Stockholm County", "North Holland"],
		    "layers_3":[12, 13, 18],
		    "layers_7":[3439]
	    },
	    "internal": false,
	    "entity": "group",
	    "entity_id": 139
    }'
```



```shell
# Response
Status Code: 201 Created
Content-Type: application/json

{
	"first_name": "Bruce",
	"last_name": "Wayne",
	"email": "bruce@waynecorp.com",
	"filters": {
		"categories": [
			578,
			23
		],
		"companies": [
			45,
			87,
			96,
			97
		],
		"departments": [
			13,
			524,
			6309
		],
		"functions": [
			882,
			4044
		],
		"locations": [
			"Gotham",
			"Gothenburg"
		],
		"location_area_1": [
			"Stockholm County",
			"North Holland"
		],
		"layers_3": [
			12,
			13,
			18
		],
		"layers_7": [
			3439
		]
	},
	"internal": false,
	"entity": "group",
	"entity_id": 139
}
```



## Request Payload

### Subscriber

| Name        | Type    | Required | Description                                                                                  |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| first\_name | string  | yes      | Subscriber first name                                                                        |
| last\_name  | string  | yes      | Subscriber last name                                                                         |
| email       | string  | yes      | Subscriber email                                                                             |
| filters     | object  | yes      | [Filters](docId\:bqYn-qUvPU9UwugPhL65G) that notify the Subscriber                           |
| internal    | boolean | no       | Subscriber is a member of the entity, so subscribe for internal jobs. Default value is False |
| entity      | string  | yes      | Entity type. `company` or `group`                                                            |
| entity\_id  | integer | yes      | ID of the entity                                                                             |

### Filters

| Name              | Type | Required | Description                                                         |
| ----------------- | ---- | -------- | ------------------------------------------------------------------- |
| categories        | list | no       | IDs of the Company categories to subscribe                          |
| companies         | list | no       | IDs of the Companies to subscribe                                   |
| departments       | list | no       | IDs of the Company departments to subscribe                         |
| functions         | list | no       | IDs of the Job functions to subscribe                               |
| locations         | list | no       | Names of the Job's cities                                           |
| location\_area\_1 | list | no       | Names of the Job's administrative level 1 location                  |
| layers\_\{x}      | list | no       | IDs of the Job layers. Replace \{x} with the dimension of the layer |

:::hint{type="info"}
The available options for all filters, can be found from the Feed API metadata. See [Feed API](docId\:eHkgl52pXl6UCtZlAEk6g) for details
:::